Канал интеграции (integration_point)

Описание

Канал интеграции в основном определяет точку обработки HTTP(s) веб-хуков, поступающих из внешних систем, а также точку для websocket подключения с предопределенными правами.
В отдельных случаях канал интеграции определяет URL внешней системы для отправки в нее HTTP запросов из сценариев.

Поддерживает потоковую асинхронную обработку сообщений, поступающих из websocket-подключений, и отправку в них ответных сообщений, а также событий.

Поддерживает создание проектных API с помощью служебных сценариев.

Websocket-подключение к каналу интеграции производится с указанием token_local непосредственно в URL или в заголовке Authorization. Подробнее.

Http(s)-подключение к каналу интеграции производится с указанием token_local. Используется для обращения к проектным API, а также для скачивания записей разговоров, вебхуков от мессенджеров.

Ограничения

  • Коллекция доступна в любом домене.

  • Лицензируется количественным параметром: расходуется лицензия на тип канала.

Поля

Структура сущности
{
  "id": uuid,
  "code": str,
  "type": str,
  "token_local": str,
  "token_remote": str,
  "token_remote2": str,
  "url": str,
  "recv_svcscriptcode": str,
  "send_svcscriptcode": str,
  "recv_svcscriptcode_ws": str,
  "send_svcscriptcode_ws": str,
  "opts": {
    "allow_files_api": bool,
    "comment": str,
    "issync": bool,
    "recv_timeout": int,
    "roles": ["special01"],
    "userid": "37a85e8-1a01-835f-4490-e78015a20052",
    "title": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

Описание характеристик спецификации

Table 1. Поля
Спецификация Описание

Поле: id
Режим: inout
Тип: uuid
По умолчанию: generated

Идентификатор. Может быть задан при создании, иначе генерируется системой.

Поле: code
Режим: in
Тип: str
По умолчанию: required

Код. Применяется для ассоциирования с другими сущностями и компонентами сценариев.

Поле: type
Режим: in
Тип: str
По умолчанию: required

Тип канала интеграции.
Количество каналов интеграции каждого типа ограничивается лицензией.

Поле: token_local
Режим: out
Тип: str
По умолчанию: generated

Локальный токен.
Используется при поступлении HTTP веб-хуков и Websocket-подключений от внешних систем к веб-серверам платформы в целях авторизации и обнаружения связанного канала интеграции.
Уникален по всем доменам.
Не подлежит модификации.

Поле: token_remote
Режим: in
Тип: str
По умолчанию: empty

Внешний токен.
Используется в привязанных сценариях для построения запросов к внешней системе.

Поле: token_remote2
Режим: in
Тип: str
По умолчанию: empty

Дополнительный внешний токен.
Может использоваться в привязанных сценариях для построения запросов к внешней системе.

Поле: remoteipmask
Режим: in
Тип: str
По умолчанию: "0.0.0.0/0"

Маска IP-адреса отправителя запроса, для которого разрешено обращение к API через данный токен.
В качестве значения IP-адреса могут выступать:

  • IP-адрес (напр. '192.168.0.10');

  • Маска подсети (напр. '192.168.0.0/24');

  • Диапазон IP-адресов (напр. '172.25.0.50+10')

Поле: recv_svcscriptcode
Режим: in
Тип: str
По умолчанию: empty | required

Код служебного сценария, запускаемого для обработки входящего HTTP-запроса с использованием token_local.
Обязательное поле для type = public.

Позволяет реализовывать проектные API.

Эндпойнт для обращения к сценарию: /api/token/v1/:TOKEN_LOCAL
В зависимости от значения поля opts.issync сценарий исполняется синхронно или асинхронно. При этом поле opts.recv_timeout задаёт предельное время ожидания выполнения сценария в секундах.

В служебный сценарий передаются на вход следующие параметры (доступны в выражениях методом startparam(N)):

  1. JSON представление сущности канала интеграции, через который поступил запрос.

  2. Метод (GET, POST, …​).

  3. Полный URL (например, http://172.27.1.112/api/token/v1/12341234-1234-1234-1234-123412341234?s=1).

  4. Содержание тела запроса.

  5. Все заголовки запроса в виде строки.

  6. IP-адрес отправителя запроса.

  7. Схема (http, https, …​)

В служебном сценарии созданы локальные строковые переменные, значения которых определяют HTTP-ответ:

  • response_code - код ответа (например 200, 404, …​)

  • response_headers - JSON-объект со специфическими заголовками для ответа. Например, {"X-Era-Test1": "bbb", "content-type": "application/json"}.

  • response_content - тело ответа. Например, {"a": 1, "b": "asdf"}.

Формат тела может быть произвольным и определяется заголовком Content-Type.

Поле: send_svcscriptcode
Режим: in
Тип: str
По умолчанию: empty

Код служебного сценария, запускаемого для отправки HTTP-запроса в канал из сценариев чат-бота

Поле: recv_svcscriptcode_ws
Режим: in
Тип: str
По умолчанию: empty

Код служебного сценария, запускаемого для обработки входящего websocket-сообщения с использованием token_local.

Позволяет реализовывать проектные API.

В рамках websocket подключения к токену метод для обращения к API сценария: ["message", {"qid": …​, "data": …​, …​}].
В зависимости от значения поля opts.issync сценарий исполняется синхронно или асинхронно. При этом поле opts.recv_timeout задаёт предельное время ожидания выполнения сценария в секундах.

В служебный сценарий передаются на вход следующие параметры (доступны в выражениях методом startparam(N)):

  1. JSON представление сущности канала интеграции, через который поступил запрос.

  2. Метод из websocket-сообщения: "message".

  3. Полный URL websocket-подключения (например, http://172.27.1.112/ws/token/v1).

  4. Содержание тела сообщения из поля 'data'.

  5. Идентификатор вебсокет-подключения.

  6. IP-адрес отправителя запроса.

  7. Схема: websocket.

В служебном сценарии созданы локальные строковые переменные, значения которых определяют HTTP-ответ:

  • response_content - содержимое ответа, размещаемое в ответное сообщение в поле 'data'. Например, {"a": 1, "b": "asdf"}. Формат может быть произвольным. JSON-объект или список отправляется в качестве ответа без дополнительного escape-форматирования.

Формат ответного сообщения:
[
  "message_result",
  {
    "qid": ...,
    "success": true,
    "data": ...
  }
]

Поле: send_svcscriptcode_ws
Режим: in
Тип: str
По умолчанию: empty

Код служебного сценария, запускаемого для отправки websocket-сообщения в канал из сценариев чат-бота

Поле: url
Режим: in
Тип: str
По умолчанию: empty

URL провайдера данных. Применяется при построении полного URL в компоненте "Веб-запрос" сценариев. Актуально для доменов с типами солюшенов, исключающими возможность указания полных адресов в свойствах компонента "Веб-запрос".

Поле: opts
Режим: in
Тип: object
Составное поле

Поле: opts.allow_files_api
Режим: in
Тип: bool
По умолчанию: false

Допуск на работу с файлами. Доступно только для type=public

Поле: opts.filter_capabilities
Режим: in
Тип: array
По умолчанию: empty

Допуск подключения по websocket на работу с конкретными Websocket Token-API. Можно перечислить конкретные, либо разрешить для всех, указав ["*"]. По умолчанию всегда разрешена capability subscribe.

Поле: opts.comment
Режим: in
Тип: str
По умолчанию: empty

Произвольный комментарий

Поле: opts.issync
Режим: in
Тип: bool
По умолчанию: false

Выключатель синхронного режима запуска сценариев, true – дожидаться ответа от сценария

Поле: opts.recv_timeout
Режим: in
Тип: int
По умолчанию: 0

Максимальное время исполнения сценария recv_svcscript в секундах. 0 означает, что будет применено значение, определённое веб-сервером (10 сек.). Максимально позволенное значение - 60 сек.

Поле: opts.roles
Режим: in
Тип: array
По умолчанию: empty

Определяет состав ролей для авторизации через сервис IAM

Поле: opts.userid
Режим: in
Тип: uuid
По умолчанию: empty

Идентификатор пользователя системы, от имени которого выполняются запросы. Применяются также роли этого пользователя.

Поле: opts.title
Режим: in
Тип: str
По умолчанию: empty

Произвольный заголовок

Поле: ext
Режим: inout
Тип: object
Составное поле

Позволяет расширять состав произвольными ключами и значениями

Поле: ext.ct
Режим: out
Тип: date
По умолчанию: generated

Время создания объекта

Поле: ext.lwt
Режим: out
Тип: date
По умолчанию: generated

Время последней модификации объекта

Типы канала интеграции

Table 2. Типы канала интеграции
Значение Описание

"public"

Канал интеграции общего назначения. Применяется при:

  • отправке HTTP-запросов из сценариев в солюшенах, имеющих ограничения по выбору URL в компоненте "Веб-запрос". Конечный URL вычисляется путем сцепления значения поля url выбранного канала интеграции, символа / и указанной страницы.

  • получении входящих HTTP-запросов от произвольных отправителей с использованием token_local. В этом случае запускается сценарий recv_svcscriptcode. В частности при получении сообщений для чат-сессий.

  • создании собственного внутреннего API в служебных сценариях на протоколах HTTP и websocket. Применяются значения полей recv_svcscriptcode, recv_svcscriptcode_ws, url и token_local, а также компонента "Отправка вебсокет-сообщения".

  • отправки сообщений из сценариев чат-ботов в канал. Применяются поля send_svcscriptcode, send_svcscriptcode_ws.

"subscr"

Канал интеграции для подписчиков на события системы.
Поддерживает подписку по протоколам HTTP и Websocket.
В первом случае отправка событий производится веб-хуками по адресу, указанному в запросе подписки, либо по адресу url.
Во втором случае отправка событий производится обратно в websocket-подключение.

В каждый канал интеграции вне зависимости от количества подключений и подписок, каждое событие отправляется не более 1 раза.

Поля recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode и send_svcscriptcode_ws не используются.

"im"

Канал интеграции для вебхуков из мессенджеров. Поступающие сообщения на страницу веб-сервера '/api/im/v1/:TOKEN' пересылаются в сервис обслуживания im-аккаунтов.

Поля url, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode и send_svcscriptcode_ws не используются.

прочие

Определяются солюшеном домена. Состав прочих типов каналов интеграции и служебные сценарии обработки содержатся в ассетах солюшена.

Характер работы аналогичен каналу "public", однако значения полей url, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode и send_svcscriptcode_ws не используются. Вместо них применяются значения, заданные в метаданных солюшена.

См. также

API

Логические роли

  • ws производит обслуживание websocket-подключений и прием HTTP веб-хуков.

  • svc производит обработку служебных сценариев, в том числе отправку HTTP-запросов компонентом "Веб-запрос".

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт