Skip to main content

API-интерфейсы менеджера

Версия: 1.26.0

API OpenRemote Manager состоит из следующих API, каждый API требует аутентификации (за исключением read/write общедоступного asset attributes, см. Asset Security).

Чтобы иметь возможность пройти аутентификацию, вам необходимо создать пользователя службы с помощью пользовательского интерфейса Manager (для доступа к этой функции необходимо войти в систему как суперпользователь), см. руководство пользователя пользовательского интерфейса Manager; токены доступа можно получить из конечной точки токена с использованием стандартных методов OAuth 2.0.

  • Конечная точка токена OAuth 2.0: /auth/realms/{realm}/protocol/openid-connect/token.
  • Типы грантов, поддерживаемые обычным пользователем: authorizationCode.
  • Типы разрешений, поддерживаемые пользователем службы: client_credentials.

HTTP API​

Это традиционный API ответа на запрос, описанный в главе REST API.

Оперативная документация также доступна через пользовательский интерфейс Swagger (см. URL-адрес /swagger/ вашего менеджера) или вы можете просмотреть демо-среду Swagger UI.

Аутентификация выполняется с использованием стандартного токена носителя заголовка Authorization, где этот токен является действительным токеном доступа, полученным из конечной точки токена OAuth 2.0.

  • Базовый URL-адрес: /api/{realm}/.
  • Заголовок авторизации: Authorization: Bearer {accessToken}.

API WS (WebSocket)​

Это API публикации и подписки, основанный на событиях, где события имеют тип SharedEvent. Аутентификация выполняется с использованием параметра запроса Authorization с действительным токеном доступа, полученным из конечной точки токена. Область аутентифицирующего пользователя также должна быть включена в качестве параметра запроса Realm.

  • URL: /websocket/events?Realm={realm}&Authorization=Bearer%20{accessToken}, например. wss://localhost:8080/websocket/events?Realm=smartcity&Authorization=Bearer%20eye2238f3a-e43c-3f54-a05a-dd2e4bd4631f

Подписки​

Подписка создается путем отправки EventSubscription как JSON с префиксом SUBSCRIBE:. Когда отправляется сообщение о подписке, сервер определяет, имеет ли запрашивающий пользователь право на такую ​​подписку, и если да, то менеджер ответит тем же объектом подписки JSON, но с префиксом SUBSCRIBED:. Если пользователь не авторизован, то объект подписки JSON будет возвращен, но с префиксом UNAUTHORIZED:.

Когда в диспетчере происходит событие, соответствующее существующей подписке, клиенту отправляется TriggeredEventSubscription в формате JSON с префиксом TRIGGERED:.

Опубликовать​

AttributeEvents можно опубликовать, и вы можете подождать, пока произойдет изменение, и будет возвращен AttributeEvent, когда атрибут действительно обновится.

Также можно эмулировать модель «запрос — ответ» HTTP API при чтении данных через WebSocket API. Для этого отправьте EventRequestResponseWrapper в формате JSON с префиксом REQUESTRESPONSE:. Поле messageId позволяет связать запрос с ответом. Такой режим можно использовать, например, для чтения актива.

Для получения более подробной информации о структуре сообщений обратитесь к Javadoc каждого типа объекта.

API MQTT (брокер MQTT)​

Еще один API публикации и подписки. Для аутентификации требуется имя пользователя и секрет 'Пользователя службы' и выполняется с использованием стандартного механизма имени пользователя и пароля MQTT для подключения к брокеру:- Хост: Хост менеджера (например, demo.openremote.io).

  • Порт: 8883 (при работе с SSL, т. е. стандартный стек с обратным прокси-сервером SSL) 1883 (при работе без прокси-сервера SSL)
  • Шифрование/TLS: true (порт 8883), false (порт 1883).
  • Имя пользователя: {realm}:{username}
  • Пароль: {secret}
  • ClientId: все что угодно (но не используйте один и тот же ClientId более одного раза)

Примечания​

  • Чтобы создать имя пользователя и секретный ключ, помните, что вам необходимо создать «Пользователя службы» (а не обычного пользователя).
  • Важно, чтобы clientId в следующих разделах совпадал с учетными данными MQTT.

Подписки​

AssetEvents​

На эти события можно подписаться, используя формат темы:

{realm}/{clientId}/asset/{assetId}

Примеры:

  • {realm}/{clientId}/asset/# — все события активов в области.
  • {realm}/{clientId}/asset/+- Все события активов для прямых дочерних элементов области.
  • {realm}/{clientId}/asset/{assetId}- Все события актива для указанного актива.
  • {realm}/{clientId}/asset/{assetId}/#- Все события актива для потомков указанного актива
  • {realm}/{clientId}/asset/{assetId}/+- Все события актива для прямых дочерних элементов указанного актива.

AttributeEvents​

На эти события можно подписаться, используя формат темы:

{realm}/{clientId}/attribute/{attributeName}/{assetId}

Примеры:

  • {realm}/{clientId}/attribute/+/# — все события атрибутов в области.
  • {realm}/{clientId}/attribute/+/+ — все события атрибутов для прямых дочерних элементов области.
  • {realm}/{clientId}/attribute/+/{assetId}- Все события атрибутов для указанного актива.
  • {realm}/{clientId}/attribute/{attributeName}/# — все события атрибута для указанного имени атрибута.
  • {realm}/{clientId}/attribute/{attributeName}/+ — все события атрибутов для прямых дочерних активов области с указанным именем атрибута.
  • {realm}/{clientId}/attribute/{attributeName}/{assetId}- Все события атрибута для указанного актива с указанным именем атрибута.
  • {realm}/{clientId}/attribute/{attributeName}/{assetId}/#- Все события атрибута для потомков указанного актива с указанным именем атрибута.
  • {realm}/{clientId}/attribute/{attributeName}/{assetId}/+- Все события атрибута для прямых дочерних элементов указанного актива с указанным именем атрибута.

Примечание

Префикс темы attributevalue можно использовать вместо attribute, чтобы возвращать только значение AttributeEvent, а не все событие.

Опубликовать​

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

  • {realm}/{clientId}/writeattributevalue/{attributeName}/{assetId} - Полезная нагрузка: JSON значения атрибута.
  • {realm}/{clientId}/writeattribute/{attributeName}/{assetId} - Полезная нагрузка: {"value": <VALUE>, "timestamp": <TIMESTAMP>}, где <VALUE> — это JSON значения атрибута, а <TIMESTAMP> — это временная метка события в миллисекундах эпохи.

Последняя публикация​

Клиенты могут настроить тему и полезную нагрузку последней воли, как определено в спецификации MQTT; тема и полезные данные могут использовать стандартную тему публикации атрибута/полезную нагрузку, поэтому можно обновить атрибут, когда клиентское соединение неожиданно закрывается; клиент должен иметь разрешение на доступ к указанному атрибуту.

Пользовательские обработчики MQTT​

Можно внедрить собственные обработчики для сообщений MQTT, реализовав абстрактный класс MQTTHandler и зарегистрировав его с помощью стандартного механизма загрузчика служб (т. е. добавив его в resources/META-INF/services/org.openremote.manager.mqtt.MQTTHandler). Пользовательский обработчик может выбрать перехват сообщений в зависимости от темы, пользователя и/или того, является ли это запросом на публикацию или подзапросом. Дополнительные сведения см. в Javadoc MQTTHandler.

Уведомление о лицензии: атрибуция документации OpenRemote