¶ 6. Внешние системы
¶ 6.1. Понятие Внешние системы
Сущность Внешние системы предоставляет интеграционные возможности для внешних систем/платформ, которым требуется данные от платформы.
Платформа предоставляет следующие способы получения данных:
- Использовать REST API платформы для получения данных по запросу.
- Получать событийную информацию в реальном времени по http протоколу. Этот вариант пододит, например, для ITSM систем, которые используют платформу как event-mng систему, для управления инцидентами и задачами в процессах ITSM.
- Получать поток данных в реальном режиме времени по протоколам MQTT, AMQP (RabbitMQ), Kafka. Этот вариант может использоваться в самых различных сценариях, где требуются данные от платформы.
¶ 6.2. Операции с Внешней системой
¶ 6.2.1. Создание Внешней системы
- Авторизоваться Суперпользователем в платформе
- Загрузить форму в меню Справочник->Внешнее приложение
- На форме создания
Внешней системызаполнить поля:
- ИМЯ ПРИЛОЖЕНИЯ - это имя будет доступно для перехода в основном меню всех приложений платформы (см. в полоске меню «
...») - ID - код приложения, внутренне имя внешеней системы, используется в топике подписки mqtt.
- url - ссылка перехода на внешнее приложение
¶ 6.2.2. Удаление редактирование Внешней системы
Операции редактирования и удаления записи Внешней системы не требуют пояснений. Отметим, что эти операции доступны только для Суперпользователя.
¶ 6.3. Настройка web-hook для отправки событий
Отправка событий во внешние системы по технологии web-hook требует применения соответствующего модуля интеграции (Inspark.Integration)
Настройка конкретных модулей интеграции см. в соответсвующем разделе модули интеграции
Для отправки событий по web-hook следует выполнить слеующие шаги:
- Авторизоваться в системе ролью не ниже
Configuration Mng(CA или SA или root). - Зайти в справочник событий на форм события.
- Отметить на форме чек бокс
Экспорт - По кнопке
Выберите внешние системы для экспортаотметьте те внешние системы, которым будут отсылаться это событие.
¶ 6.4. Настройка подписки на брокер MQTT, AMQP
Платформа отправляет данные по mqtt, или AMQP в роли клиента внешнего брокера. Перед настройкой подписки необходимо уточнить параметры подключения к брокеру.
- Авторизоваться Суперпользователем в платформе
- Загрузить форму в меню Справочник->Внешнее приложение
- Выбрать запись конкретной внешней системы.
- На форме
Внешней системывыбрать подпункт меню: Подписка MQTT, Подписка AMQP - Создать запись подписки MQTT, ввести данные подключения (для протокола AMQP аналогично):
- url mqtt брокера;
- логин/пароль;
- порт.
- Нажать кнопку
Параметры, и выбрать в модальном окне список параметров, которые требуются передать.
Виды авторизации:
- TRUST(1) - Авторизация не требуется;
- PASSWD(2) - Авторизация с помощью логина и пароля;
- TLS12(3) - Авторизация TLS v1.2
Если брокер не требует авторизации, следует указать тип авторизации authType = TRUST(1) (доверенная авторизация, характерна для брокеров находящихся в одной сети, управление доступов в таком случае осуществляется средстами брэндмаура или политиками безопаности на уровне портов/приложений)
Если на брокере настроен ACL плагин HTTP авторизации, по логину и паролю - следует задать тип авторизации authType = PASSWD(2) и значения brokerUser и brokerPassword.
Для TRUST(1) и PASSWD(2) коннект задается , как показано ниже
tcp://<имя хоста/адрес>:<порт>,
Например:
tcp://10.3.2.38:1883
Если на брокере установлена поддержка авторизации с открытым ключем TLS v1.2 - следует указать тип авторизации authType = TLS12(3) и загрузить сертификаты в атрибуты:
- certCa (корневой CA сертификат для авторизации брокера)
- cert (сертификат клиента, с которым мы будем авторизовываться в брокере)
- certKey (приватный ключ сертификата клиента)
Сертификаты загружаются в виде текста их содержимого и сохраняются как есть без каких-либо преобразований.
Так же следует корректно задать brokerUrl, в данном случае он должен начинаться с протокола SSL и содержать имя машины для подключения, например «ssl://ubuntu20:8883». При этом машина брокера (в этом примере ubuntu20) должна быть доступна в сети по этому имени и имя должно соответствовать записи «Common Name» клиентского сертификата (и брокерного сответственно тоже).
Поддерживается два формата передачи данных:
- JSON;
- ANDROMEDA.
Формат передачи данных и событий для MQTT:
Измерения:
mqtt-topic = /inspark/{ext_system_id}/measures/out/PARAMID - для измерений по параметру PARAMID, где PARAMID это (ContrDeviceParam.id для измеряемых, ContrCalcParam.id для вычисляемых)
mqtt-message = {"id":33013,"value":"7.0","time":1707393139000, "paramCode": <альтернативный код параметра>, "statusID": 0 } - json объект, где:
id - идентификатор параметра PARAMID
value - значение
time - время значения в формате юникс (миллисекунды)
paramcode - альтернативный код, может использоваться для интеграций. Например, внешней системе надо, чтобы значение по параметру содержала какой-то их код. Такой код можно в ЛК записать в поле paramcode.
statusID - системный статус парамтра, может присылать значения «Норма»-1, «Отклонение»-2, «Критическое»-3, «Недостоверно»- (-1) и «Нет контроля» - 0.
События:
mqtt-topic = /inspark/{ext_system_id}/events/out/EVENTID - топик формируется составным, с участием идентификатора внешней системы и типа события, где EVENTID это идентификатор типа параметра (Event.id)
mqtt-message = {"id":29052,"eventId":5003,"time":1707393189000,"msg":"Усё пропало, шеф"} - json объект, где:
id - идентификатор записи журнала событий (EventLog.id)
eventId - идентификатор типа события, EVENTID
time - время события в формате юникс (миллисекунды)
msg - текст события (EventLog.message)
Для формата ANDROMEDA публикуются только значения параметров (события не публикуются).
mqtt-topic = PARAM-CODE - в качестве топика выступает код параметра (поле Альтернативный код в измерениях)
mqtt-message = VALUE - в качестве сообщения топика публикуется значение параметра строкой
Для RabbitMQ данные публикуются в 2 очереди:
inspark-event - в нее публикуются события, в формате JSON объекта
inspark-measure - в нее публикуются измерения, в формате JSON объекта
Формат данных точно такой же как и для MQTT JSON пакета
¶ 6.5 Общая информация по сертификатам
Есть как бы три таких вот группы по ответсвенностям: админ CA, брокер, клиент.
Админ CA, который хранит корневой сертификат CA и сложный секретный ключ к нему. Он его может сгенерировать или где-то получить, это его ответсвенность. Хранит в сейфе, ибо потерял - и все пропало 
- ca.crt - ca.key
Брокер, который хранит свой приватный ключ broker.key. На основании этого ключа запрашивает у админа CA сертификат (создает запрос сертификата broker.csr и отправляет его каким-то образом админу CA), тот генерирует ему подписанный сертификат broker.csr и отправляет назад). Таким образом у брокера: - ca.crt - broker.crt - broker.key
Клиенты брокера, каждый хранит свой приватный ключ client.key. Аналогично брокеру, они формируют запрос к админу CA на создание сертификата, при этом в запросе указывают имя «Common Name» то же что указал брокер в запрос своего сертификата (он должен как-то им сообщить). Админ CA формирует клиенту клиентсткий сертификат client.crt. Таким образом у клиента: - ca.crt - client.crt - client.key