Получение и визуализация данных из Битрикс24 без навыков программирования05.10.2023 10:01

Год назад у Битрикс24 появилась нативная интеграция с BI‑сервисом DataLens, и теперь пользователи CRM могут строить дашборд с бизнес‑аналитикой за несколько кликов. Для создания таких аналитических отчётов бизнес обычно объединяет все данные в единую базу. При таком подходе можно накладывать данные друг на друга, искать пересечения и строить обобщённые визуализации. Но в интерфейсе Битрикс24 такой возможности нет, а значит для создания единой базы нужны программисты.

В этом материале покажу, как настроить интеграцию Битрикс24 со сторонней базой данных, даже если вы вообще не знаете языков программирования.

Дисклеймер: Это бета‑версия скрипта для импорта лидов, сделок, контактов и компаний из Битрикс24 от участника сообщества DataLens. Если встретите ошибку или возникнут вопросы, пишите в телеграм https://t.me/polyakovbest

Что делаем

Наша задача — простым и безопасным способом передавать данные по лидам, сделкам, контактам и компаниям из Битрикс24 в базу данных, которая станет источником для DataLens.

Да, для подобных задач передачи данных существуют сторонние сервисы —, но в этом случае нельзя гарантировать недоступность информации третьим лицам и отсутствие уязвимостей, которые могут привести к утечке данных.

Поэтому мы сделаем так:

  • передадим в базу данных информацию из Битрикс24;

  • настроим функцию в облаке, которая будет работать как обозреватель для изменений данных Битрикс24. Для этого пригодятся возможности Yandex Cloud Functions.

Это поможет создать актуальные отчёты DataLens, которые будут содержать все данные, в том числе дополнительные пользовательские поля, взятые из разных систем.

Схема действий: пользователь заполняет файл с анкетой конфигурации, скачивает и запускает Docker (это одна строчка в консоли). Остальные действия выполняются внутри исполняемого Docker-образа.

Схема действий: пользователь заполняет файл с анкетой конфигурации, скачивает и запускает Docker (это одна строчка в консоли). Остальные действия выполняются внутри исполняемого Docker-образа.

Как подготовиться

Прежде чем настраивать автоматизацию пройдёмся по необходимым подготовительным шагам:

  • Получить доступ в базу данных, в которой будет храниться выгрузка. В этой базе уже должны быть созданы таблицы для приёма данных.

    Необходимо получить доступы в формате: host, port, user, password, db_name.
    А также выяснить названия полей в базе‑приёмнике.

    Если ваша база данных ClickHouse — то для работы с данными из CRM обязательно создать таблицы на движке VersionedCollapsingMergeTree (`sign` Int8, `version` UInt32).

  • Создать входящий вебхук в Битрикс24 на получение данных из CRM.
    Входящий вебхук позволит выгрузить имеющиеся данные из Битрикс24 в базу.

    Создать вебхук можно в разделе для разработчиков Битрикс24, в подразделе Другое: Инструкция на сайте Поддержки24

  • Там же нужно проверить, что у нас есть возможность настроить исходящий вебхук из Битрикс24.
    Одна из задач в этой статье — настроить облачную функцию-наблюдатель для данных, которые поступают из Битрикс24. Для этого мы должны дать возможность системе Битрикс24 обратиться к нашей облачной функции и что‑то ей передать.

  • Зарегистрироваться в Yandex Cloud. Убедиться, что можем создавать Cloud Functions.
    Зарегистрироваться можно на сайте Yandex Cloud. Затем в консоли управления облака необходимо зайти в любой каталог и из него выбрать сервис Cloud Functions.

Выгрузка данных из Битрикс24 в базу

Сначала мы запустим Docker‑контейнер, который создаст для нас весь код облачной функции для обработки событий поступающих из Битрикс24.

  1. Скачать и установить дистрибутив Docker с официального сайта.

  2. Скачать архив с кодом программы из репозитория и распаковать его.

c9f1f8f89b449c9d94fd22144e36e7af.png

  1. Из распакованного архива открыть файл config.example.yaml в текстовом редакторе и заполнить:

    • авторизационную информацию Битрикс24,

    • авторизационную информацию базы данных, полученную на подготовительном шаге,

    • настройки переноса данных: какие данные в какие поля будем переносить. В образце задана возможность экспорта всех разделов Битрикс24, но при желании ненужные можно пропустить, например, экспортировать только сделки. Названия нужных полей в Битрикс24 можно легко найти через инструменты разработчика в консоли браузера.

Надо заполнить нужные нам поля реальными данными или присвоить им null, если их экспорт не нужен. Комментарии к заполнению на английском написаны в файле.

Надо заполнить нужные нам поля реальными данными или присвоить им null, если их экспорт не нужен. Комментарии к заполнению на английском написаны в файле.

После этого сохранить файл там же с именем config.yaml

  1. Открыть терминал, перейти в директорию с распакованным архивом и заполненными настройками с помощью команд:

    • cd и ls для Linux и MacOS,

    • cd и dir для Windows.

  2. Выполнить команду: 

docker build -t your-image-name

Docker скачает все необходимые библиотеки для запуска.

  1. Открыть Docker Desktop и запустить образ:

Кнопка для запуска образа.

Кнопка для запуска образа.

Создание кода для функции в Yandex Cloud

Для следующего шага ждём появления текста import started:

Deal import started — значит данные о структуре всех таблиц получены, сохранены и помещены в директорию с файлами облачной функции.

Deal import started — значит данные о структуре всех таблиц получены, сохранены и помещены в директорию с файлами облачной функции.

С этого момента Docker начал выполнять выгрузку данных из истории Битрикс24, и это означает, что файлы виртуальной функции уже готовы — они появляются после теста проверки подключения к базе и получения данных о таблицах в ней.

Чтобы скачать файлы облачной функции, надо пройти во вкладку Files и перейти в директорию App приложения Docker Desktop.

Расположение файлов: 1. Files. 2. App 3. cf (для скачивания).

Расположение файлов: 1. Files. 2. App 3. cf (для скачивания).

Нас интересует папка с именем cf (cloud function). Нажимаем по ней правой кнопкой и сохраняем на диск через диалог Save.

Создаём архив из всех скачанных файлов.

Синим выделены файлы, которые нужно добавить в архив.

Синим выделены файлы, которые нужно добавить в архив.

Если у вас MacOS, то открываем терминал, переходим в папку с созданным архивом и выполняем команду zip -d Архив.zip »__MACOSX/*» 

zip -d Архив.zip "__MACOSX/*”

Удаление временных файлов из архива для MacOS.

Удаление временных файлов из архива для MacOS.

Это нужно, чтобы исключить в файле архива наличие мусора — сборщику функций Yandex Cloud понадобится чистый архив.

Настраиваем функцию в Яндекс.Облаке

Заходим на https://cloud.yandex.ru. Переходим в Консоль >> Все сервисы >> Cloud Functions. Нажимаем Создать функцию.

Расположение кнопки создания новой функции.

Расположение кнопки создания новой функции.

  1. Вводим имя и описание

  2. Среда Python 3.11, файлы с примерами кода не нужны.

  3. Нужно выбрать Zip-архив >> Прикрепить файл >> Выбираем созданный на прошлом шаге архив.

  4. Спускаемся ниже и указываем точку входа index.handler.

  5. Ещё ниже. Выставляем таймаут 10 секунд.

  6. Нажимаем кнопку вверху справа Создать версию.

  7. После того как попадем во вкладку Обзор, выставляем флаг Публичная функция и копируем ссылку на функцию.

1. Установка доступа к функции извне. 2. Адрес, по которому функцию можно разбудить.

1. Установка доступа к функции извне. 2. Адрес, по которому функцию можно разбудить.

  1. В Битрикс24 открываем раздел Разработчикам >> Другое и создаём исходящий вебхук. В поле для ссылки вводим адрес нашей функции.

Копируем себе идентификатор приложения (токен) — он ещё понадобится.

Проставляем те события, наблюдателем которых должна быть наша функция.

Пример настройки исходящего вебхука в Битрикс24.

Пример настройки исходящего вебхука в Битрикс24.

  1. Возвращаемся в нашу функцию в консоли управления Yandex Cloud. Открываем Редактор.

Внизу редактора создаём переменную окружения с именем app_token и значением токена приложения из предыдущего шага.

  1. Создаём версию. Функция готова.

Если импорт сделок в Docker закончился, то можно удалить образ, он нам больше не понадобится. Для этого можно использовать: 

docker ps -a
docker rm ####

Сначала выполните первую команду. Затем найдите имя вашего контейнера и используйте его вместо ### во второй команде.

Как проверить, что всё работает

Идём в Битрикс24 и вносим любое изменение в отслеживаемую сущность. Например, в сделку, если вы настраивали функцию на их отслеживание.

После этого переходим в нашу созданную функцию и открываем вкладку «логи». Если там есть запись о совершенном импорте и нет ошибок — значит, всё работает как надо.

Примеры ошибок.

Примеры ошибок.

П

Примеры успешного обновления данных.

Бонусы для знакомых с Python

Как сделать свой собственный препроцессинг данных

Данный скрипт самостоятельно обрабатывает nullable‑поля, преобразовывает строки в числа, числа в строки там, где это необходимо. Но бывают случаи, когда простым препроцессингом не обойтись и надо преобразовать данные по сложной логике, например, для списочных свойств. На этот случай в настройках есть специальные поля:

В файле config.example.preproc.yaml есть внесённые значения для функций.

В файле config.example.preproc.yaml есть внесённые значения для функций.

В файле config.example.yaml проставлены null, этот файл для тех, кто не будет писать собственные функции предобработки.

В файле config.example.yaml проставлены null, этот файл для тех, кто не будет писать собственные функции предобработки.

  1. Чтобы пользоваться препроцессингом данных, надо написать специальную функцию и разместить её в файле preprocessing_functions.py.

Следует предусмотреть в этой функции сразу все возможные манипуляции, включая обработку null, так как встроенный препроцессинг не будет запускаться для этих значений.

  1. Имя функции написать в файле config.yaml.

Функции пишутся на Python. Пример функции: 

def add_million_to_id(value: str) -> int:
    return int(value) + 1000000

  1. Чтобы проще ориентироваться в содержании данных, я сделал отдельный метод, который можно запустить в терминале из директории проекта: 

python show_values.py

91d662382b49cc167cd6ec6014a00d26.png

Как узнать список полей Битрикс24 и их идентификаторы

В архиве проекта есть скрипт на языке Python, который можно запустить, заполнив информацию о вебхуке Битрикс24 из предварительного шага. Скрипт выведет все существующие поля для данных из вашего Битрикс24. 

python show_fields.py

9e58d3a6b68654a048163e133839322d.png

Как решать возможные проблемы с окружением Python

Последняя мини-инструкция поможет, если на вызов в консоли 

python3 show_fields.py

мы получаем ошибку вида: 

Traceback (most recent call last):
File "/Users/master/Dropbox/Analytics x AWST/Статьи/Импорт данных
из б24 в базу/show_fields.py", line 1, in 
import requests
ModuleNotFoundError: No module named 'requests'

Для решения нужно 2 шага.

  1. Узнаём, где у нас расположено окружение Python: 

which python3

Получаем вывод: 

/opt/homebrew/bin/python3

  1. Установим необходимые для работы библиотеки по обнаруженному адресу: 

/opt/homebrew/bin/python3 -m pip install --upgrade pip
/opt/homebrew/bin/python3 -m pip install requests
/opt/homebrew/bin/python3 -m pip install pyyaml

© Habrahabr.ru