Документация Accelera
Кастомизация

Создание действия для Segments

При необходимости интеграций со сторонними системами методами, которые отсутствуют в стандартном наборе Accelera Segments, в системе есть возможность создать собственное действие.

Его задача - получить задачу и выполнить необходимый (например, запрос в одну из систем вашей компании или отправка PUSH-уведомления).

Экшн принимает входящий датасет для его последующей обработки.

Вы можете создать собственное действие на любом подходящем для вас языке программирования. Главное требование - возможность подключения к RabbitMQ версии > 3.5.0, RabbitMQ имеет множество клиентских библиотек.

Последовательность взаимодействия

  1. Необходимо зарегистрировать экшны, отправив необходимый JSON в очередь FLOWS.segments-custom-actions-register.

  2. Подписаться на очередь для получения задач. Есть два способа:

    Способ 1 (простой): Подписаться на очередь FLOWS.segments-custom-actions.{serviceName}, где {serviceName} — переменная среды SEGMENTS_SERVICE_NAME из настроек сегмента (по умолчанию segments-service).

    Способ 2 (с балансировкой нагрузки): Создать очередь с произвольным именем и привязать (bind) её к fanout exchange ex-segment-custom-actions.{serviceName}. Это позволяет запускать несколько инстансов вашего модуля: если все инстансы создают очередь с одинаковым именем, RabbitMQ будет распределять сообщения между ними (round-robin), и каждое сообщение обработает только один инстанс.

  3. Фильтрация сообщений. Поскольку в одну очередь могут приходить задачи для разных экшнов, при получении сообщения необходимо проверить поле name — совпадает ли оно с именем вашего экшна.

    • Если совпадает — обработать сообщение.
    • Если не совпадает — подтвердить (ack) и пропустить. Не используйте nack/reject для чужих сообщений — это приведёт к зацикливанию сообщения в очереди.

  4. При выполнении сегментов будут отправляться задачи в указанную очередь. Задачи приходят в формате:

{
    "name": "<имя экшна>",
    "data": {
        "<параметры, заданные пользователем при настройке экшна>"
    },
    "meta": {
        "segmentId": "<id сегмента>",
        "startupId": "<идентификатор запуска>",
        "trigger": "<вид запуска: test — тестовый, start — боевой>",
        "nodeId": "<идентификатор ноды>",
        "nodeClass": "<имя экшна>",
        "segment_name": "<имя сегмента>",
        "initiator": "<username пользователя, кто запустил>",
        "inputTable": "<имя таблицы с данными предыдущего шага>"
    }
}

Поле meta.inputTable содержит готовое имя таблицы в базе данных, из которой нужно читать входящий датасет. Вычислять имя таблицы вручную не требуется.

  1. Тестовый режим. Если meta.trigger равен test, экшн должен сразу вернуть статус success без реальной обработки. Это используется для проверки что экшн доступен и корректно зарегистрирован.
  2. При обработке необходимо сообщить системе статус обработки экшна (при успешном завершении — success, при ошибке — error). Опубликовать необходимо в очередь FLOWS.custom-actions-statuses. JSON статуса — это полученный ранее объект сообщения с дополненным meta:
{
    "name": "<имя экшна>",
    "data": { "<параметры>" },
    "meta": {
        "segmentId": "<id сегмента>",
        "startupId": "<идентификатор запуска>",
        "trigger": "<вид запуска>",
        "nodeId": "<идентификатор ноды>",
        "nodeClass": "<имя экшна>",
        "segment_name": "<имя сегмента>",
        "initiator": "<username пользователя>",
        "inputTable": "<имя входной таблицы>",
        "status": "<success или error>",
        "error": "<текст ошибки, если статус error>",
        "counter": "<количество обработанных строк>",
        "statement": "<SQL-запрос, который был выполнен, при наличии>"
    }
}

Контрольные сигналы

Система поддерживает управление выполнением экшнов в реальном времени через контрольные сигналы. Это особенно важно для долгих операций (стриминг больших датасетов).

Подключение

Создайте очередь и привяжите (bind) её к fanout exchange ex-segments-control.{serviceName}.

Для контрольных сигналов каждый инстанс должен создавать уникальную очередь (например, с random-суффиксом в имени). Это необходимо чтобы сигнал получили все инстансы — отреагирует тот, у которого данный сегмент реально в обработке.

Рекомендуемые параметры очереди: exclusive, autoDelete, x-message-ttl: 300000 (5 минут). Это гарантирует автоматическую очистку очереди при отключении инстанса.

Формат сигнала

{
    "signal": "stop",
    "segmentId": "<id сегмента>",
    "startupId": "<идентификатор запуска>",
    "reason": "<причина остановки>",
    "timestamp": 1719500000000
}

Поле signal может принимать значения: stop, pause, resume.

Обработка

Поскольку exchange является fanout, все инстансы получают все сигналы. При получении сигнала необходимо:

  1. Проверить segmentId — есть ли у вас в обработке этот сегмент.
  2. Если нет — подтвердить (ack) и пропустить.
  3. Если да — выполнить действие:
    • stop — прекратить обработку, закрыть ресурсы (потоки данных, соединения), отправить статус error с описанием причины остановки.
    • pause — приостановить обработку.
    • resume — возобновить обработку.

Throttling

При стриминге больших датасетов рекомендуется ограничивать скорость обработки (throttling), чтобы не перегружать целевые системы. Типичный подход — ограничение количества обрабатываемых строк в секунду. Значение по умолчанию в системе — 300 строк/сек.

Параметры экшнов

Структура

Пример JSON для регистрации экшна

{
  "title": "Create and publish offer",
  "name": "createOffer",
  "icon": "fe fe-user-plus",
  "data": {
    "campaignType": "",
    "channels": [],
    "isCustomJS": true,
    "isCustomHTML": true,
    "svgIcon": true
  },
  "html": "<div>...HTML модального окна..</div>",
  "icon": "<svg></svg>",
  "script": "console.log('test')",
  "webhooks": "http://127.0.0.1:5071",
  "parameters": [
    {
      "name": "campaignType",
      "label": "Campaign type",
      "type": "dropdown",
      "options": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "name": "textAttributes",
      "label": "Text attributes",
      "type": "list",
      "hidden": "true",
      "fields": [
        {
          "Name": "Text attribute 1",
          "type": "inputSingleColumn",
          "Content": ""
        },
        ...
      ]
    },
    {
      "name": "channels",
      "type": "dynamicList",
      "fields": [
        {
          "name": "Channel",
          "type": "dropdown",
          "options": [
            "1",
            "2",
            "3",
            "4"
          ]
        },
        {
          "name": "Templates",
          "type": "number"
        }
      ]
    }
  ]
}

Описание параметров

title - Подпись экшна, можно использовать кириллицу/латиницу, пробелы, символы и тд.

name - Код экшна, должен быть уникальным, не содержать пробелов, спец.символов и тд.

icon - Иконка экшна. Необязательное поле, по умолчанию экшн получает стандартную иконку. Если svgIcon: true в data, то в поле icon можно передать SVG-разметку. Иначе используйте CSS-класс из таблицы рекомендуемых иконок.

data - перечисление всех параметров, которые будут приходить в экшне в виде объекта. Также поддерживает служебные флаги:

  • isCustomJS: true — использовать кастомный JavaScript из поля script
  • isCustomHTML: true — использовать кастомный HTML из поля html
  • svgIcon: true — использовать SVG-иконку из поля icon

parameters - схема параметров, с описанием их типов и значений. Поле name в каждом параметре должно совпадать с параметром из data.

html - HTML код модального окна

script - JavaScript код, выполняемый при загрузке окна. При обработке сохранения формы модального окна должен быть сформирован объект с данными и выполнен вызов метода save_data_segment_custom_action(data), передав ему сформированный объект.

webhooks - URL для HTTP-запросов со стороны интерфейса Accelera к экшну, например для обогащения данными модального окна. Запросы выполняются методом POST.

Доступные типы полей

ТипОписание
inputОбычное текстовое поле
inputTableПоле для названия таблицы. Нельзя начинать с цифры, запрещены пробелы и символы кроме - и _
inputSingleColumnПоле для выбора одного варианта
inputMultiColumnПоле для выбора множества вариантов
constantНеизменяемое поле
dropdownПринимает массив параметров, выбирается одна опция.
numberПоле для ввода чисел
textТекстовое поле, которое можно расширять
listПостоянный список текстовых атрибут
dynamicListДинамический список атрибут
calendarПоле календаря

Возможные иконки для действий (action'ов)

Код иконкиОписание
fe fe-user-plusПользователь с символом +
fe fe-user-minusПользователь с символом -
fe fe-user-xПользователь c символом х
fe fe-linkСимвол ссылки
fe fe-user-checkПользователь c символом v
fe fe-rssСимвол rss
fe fe-mailИконка e-mail
fe fe-message-circleИконка SMS-сообщения

Webhooks

Для обогащения модального окна, в параметрах экшна можно указать URL в поле webhooks, по которому интерфейс Accelera будет запрашивать данные. Для вызова этого URL в Accelera нужно вызвать метод custom_webhooks(action_name, data), где action_name — это имя экшна, а data — объект, который будет отправлен в POST-запросе. Запрос выполняется только методом POST.

При использовании кастомного кода в модальном окне, ручная обработка сохранения данных через script обязательна. Несмотря на то что окно формируется скриптами и HTML со стороны, указание полей в объекте data в JSON-структуре экшна остаётся обязательным.

Кастомизация

Предыдущая страница

Создание действия для Flow

Следующая страница

На этой странице

Последовательность взаимодействияКонтрольные сигналыПодключениеФормат сигналаОбработкаThrottlingПараметры экшновСтруктураWebhooks