Перейти к основному содержанию

Протоколы для внешних систем

8 января 2025 г.Около 3 мин

Публикация данных

MQTT

По протоколу MQTT поддерживаются 2 формата:

  • общий формат JSON;
  • специальный формат брокера MQTT системы АНДРОМЕДА (Сбер).

формат JSON

Измерения:
topic:

/inspark/{ext_system_id}/measures/out/PARAMID

для измерений по параметру PARAMID, где PARAMID это (ContrDeviceParam.id для измеряемых, ContrCalcParam.id для вычисляемых)

message:

{"id":33013,"value":"7.0","time":1707393139000, "paramCode": "SYS-4-3", "stateId": 3}

где:

  • id - идентификатор параметра PARAMID (ContrDeviceParam.id или ContrCalcParam.id)
  • value - значение
  • time - время значения в формате юникс (миллисекунды)
  • paramCode - интеграционный код параметра
  • stateId - статус параметра (идентификатор)

События:
topic

/inspark/{ext_system_id}/events/out/EVENTID

топик формируется составным, с участием идентификатора внешней системы и типа события, где EVENTID это идентификатор типа параметра (Event.id)

message:

{"id":33013,"eventId":"2019","time":1707393139000, "msg":"Потеряна связь с контроллером"}

где:

  • id - идентификатор записи в журнале событий ((EventLog.id)).
  • eventId - идентификатор типа события (Event.id)
  • time - время значения в формате юникс (миллисекунды)
  • msg - текст сообщения

формат ANDROMEDA

Для формата публикуются только значения параметров (события не публикуются).

mqtt-topic   = PARAM-CODE - в качестве топика выступает код параметра (ContrDeviceParam.paramcode для измеряемых, ContrCalcParam.paramcode для вычисляемых)
mqtt-message = VALUE - в качестве сообщения топика публикуется значение параметра строкой

Настройки публикации

Описание настройки см. в разделе администратора.

Про сертификаты

Есть три группы по ответсвенностям: админ 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

Kafka

Топики по умолчанию

В брокере Apache Kafka должны быть заведены очереди (по умолчанию или те что прописаны в настройках публикации):

  • inspark-event - в нее публикуются события, в формате JSON объекта
  • inspark-measure - в нее публикуются измерения, в формате JSON объекта

ВАЖНО

Очереди должны быть заведены и существовать в Apache Kafka до запуска публикации.

Формат сообщений:

Измерения в формате JSON содержат следующие данные:

{"id":33013,"value":"7.0","time":1707393139000, "paramCode": "SYS-4-3", "stateId": 3}

где:

  • id - идентификатор параметра (ContrDeviceParam.id или ContrCalcParam.id)
  • value - значение
  • time - время значения в формате юникс (миллисекунды)
  • paramCode - интеграционный код параметра
  • stateId - статус параметра (идентификатор)

События в формате JSON содержат следующие данные:

{"id":33013,"eventId":"2019","time":1707393139000, "msg":"Потеряна связь с контроллером"}

где:

  • id - идентификатор записи в журнале событий ((EventLog.id)).
  • eventId - идентификатор типа события (Event.id)
  • time - время значения в формате юникс (миллисекунды)
  • msg - текст сообщения

ВАЖНО

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

Настройка публикации

Описание настройки см. в разделе администратора.
Для подключения важно указать

  • bootstrapAddress - Адрес подключения (хост:порт). Пример 192.168.1.15:9092
  • measureTransformUrl - URL HTTP сервера для трансформации измерений.
  • eventTransformUrl - URL HTTP сервера для трансформации событий.
  • measureTopic - Топик для отправки измерений. Если не задан - используется топик по умолчанию.
  • eventTopic - Топик для отправки событий. Если не задан - используется топик по умолчанию.

RabbitMQ протокол AMQP

Топики по умолчанию

В брокере RabbitMQ должны быть заведены очереди (по умолчанию или те что прописаны в настройках публикации):

  • inspark-event - в нее публикуются события, в формате JSON объекта
  • inspark-measure - в нее публикуются измерения, в формате JSON объекта

ВАЖНО: очереди так же могут быть сконфигурированы в таблице ext_system_amqp_config (measure_topic, event_topic). Но в любом случае они должны быть заведены и существовать в RabbitMQ до запуска публикации.

Формат сообщений:

Измерения в формате JSON содержат следующие данные:

{"id":33013,"value":"7.0","time":1707393139000, "paramCode": "SYS-4-3", "stateId": 3}

где:

  • id - идентификатор параметра PARAMID (ContrDeviceParam.id или ContrCalcParam.id)
  • value - значение
  • time - время значения в формате юникс (миллисекунды)
  • paramCode - интеграционный код параметра
  • stateId - статус параметра (идентификатор)

События в формате JSON содержат следующие данные:

{"id":33013,"eventId":"2019","time":1707393139000, "msg":"Потеряна связь с контроллером"}

где:

  • id - идентификатор записи в журнале событий ((EventLog.id)).
  • eventId - идентификатор типа события (Event.id)
  • time - время значения в формате юникс (миллисекунды)
  • msg - текст сообщения

ВАЖНО

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

Настройка публикации

Описание настройки см. в разделе администратора.
Для подключения важно указать

  • host - IP-адрес или имя машины с брокером сообщений
  • port - порт подключения (обычно 5672).
  • virtualHost - Виртуальный хост. Аналог каталога. По умолчанию обычно "/"
  • username - Логин пользователя брокера.
  • password - Пароль пользователя брокера.
  • measureTransformUrl - URL HTTP сервера для трансформации измерений.
  • eventTransformUrl - URL HTTP сервера для трансформации событий.
  • measureTopic - Топик для отправки измерений. Если не задан - используется топик по умолчанию.
  • eventTopic - Топик для отправки событий. Если не задан - используется топик по умолчанию.

Отправка команд

Внешние системы также могут отправить в платформу команду на изменение данных. Поддерживаются все три брокера (MQTT, RabbitMQ, Apache Kafka).

Для приема команд из внешних систем следует задать топики приема внешних команд и получения ответа). При поступлении в топик приема команды соответствующего формату сообщения публикатор обработает ее и отправит уведомление (если сконфигурирован топик результатов, см ниже).

Команда принимается в формате JSON:

{"command": "SET_VALUE", "id": "123-123", "paramCode": "33013/para-code", "value": "25"}
    • command - тип команды
  • SET_VALUE используется для установки значения параметру, участвующему в публикации. При получении команды модуль публикации выполняет поиск параметра по коду (paramCode) среди параметров публикации, формирует для него сообщение JMS в очередь SetValue и отправляет сообщение в очередь. В случае если сконфигурирован топик отправки результата (описание ниже) - отправляет уведомление об успешном выполнении команды. В случае если не удалось разобрать команду, найти параметр - отправляет сообщение результат с ошибкой выполнения.
  • id - уникальный идентификатор команды
  • paramCode - уникальный код параметра в рамках публикации (ContrDeviceParam.paramcode или ContrCalcParam.paramcode)
  • value - значение

Ответ будет отправлен в топик уведомления:

{"id": "123-123", "error": "усе пропало шэф"}
  • id - уникальный идентификатор команды
  • error - сообщение об ошибке (при успешном выполнении команды = null)

Например, для MQTT обмена заданы топики:

  • для отправки команд : /inspark/<ext_system_id>/request
  • для получения ответа о выполнении команд : /inspark/<ext_system_id>/response

В первый топик отправляет посылку (см. выше), а во втором ловим код команды ("123-123") , чтобы определить как она выполнилась.

Последнее обновление: 31.01.2025, 15:29:21
Контрибьюторы: gukovi,Igor
© 2013-2025 Inspark Ltd. All rights reserved