Подключение при помощи Management API
Описание процесса
Заголовок раздела «Описание процесса»Для подключения устройства данным способом необходимо настроить интеграционный контракт с платформой посредством создания и конфигурирования требуемых сущностей.
Шаги настройки:
- Создайте общую папку
- Создайте интеграционную конфигурацию
- Запустите интеграционную конфигурацию
- Создайте действия (actions)
- Создайте скрипт на получение команд
- Осуществите валидацию скрипта
- Запустите скрипт
- Создайте операции
- Запустите входящие операции
- Создайте адреса подключения (endpoints) к платформе
- Запустите адреса подключения к платформе
- Создайте хост для подключения к устройству
- Создайте адрес для подключения к устройству
- Создайте исходящую операцию
Создание общей папки
Заголовок раздела «Создание общей папки»POST api/v1.1/integration/folder
Пример тела запроса:
{ "name":"Папка для конфигураций"}Создание интеграционной конфигурации
Заголовок раздела «Создание интеграционной конфигурации»POST api/v1.1/integration/configuration
Пример тела запроса:
{ "name":"Интеграционная конфигурация", "folderId":"{{ID папки}}", "logLevel":"Error", "errorItemIds":[], "defaultTimeout":30000}Запуск интеграционной конфигурации
Заголовок раздела «Запуск интеграционной конфигурации»POST api/v1.1/integration/сonfiguration/{ID интеграционной конфигурации}/deploy
Создание действий (actions)
Заголовок раздела «Создание действий (actions)»Действие на авторизацию
Заголовок раздела «Действие на авторизацию»POST api/v1.1/integration/action
Пример тела запроса:
{ "actionTypeId": "4d58067f-cc13-42c9-b53d-e5e0a214786a", "folderId": "{{ID папки}}", "parameters": [ { "actionTypeParameterName": "token", "valueTypeId": "ff791c0a-925e-4117-8193-6e615e6bbecb", "value": "$.payload.username" } ]}Действие на извлечение request_id из входящего запроса
Заголовок раздела «Действие на извлечение request_id из входящего запроса»POST api/v1.1/integration/action
Пример тела запроса:
{ "actionTypeId": "0a9566c1-9a21-4a53-9d30-302ed422453d", "folderId": "{{ID папки}}", "parameters": [ { "actionTypeParameterName": "regexp", "valueTypeId": "f6898ec0-cb22-4184-a511-cf728f8d1205", "value": "v1/devices/me/rpc/request/([0-9]+)" }, { "actionTypeParameterName": "from", "valueTypeId": "ff791c0a-925e-4117-8193-6e615e6bbecb", "value": "$.endpoint.uriPath" // или $.request.context.endpoint.topic }, { "actionTypeParameterName": "to", "valueTypeId": "ff791c0a-925e-4117-8193-6e615e6bbecb", "value": "$.contextVariables.externalRqId" } ]}В комментариях показан пример для MQTT.
Создание скрипта на получение команд
Заголовок раздела «Создание скрипта на получение команд»POST api/v1.1/integration/script
Пример тела запроса:
{ "name":"Получение команд", "folderId":"{{ID папки}}", "body":"function convert(message, context) { return { id: '{{externalRqId}}', method: '{{methodName}}', params: message};}; convert(message, context);", //id - опционален, methodName - название метода "expectedParams":{}, "timeout":30000}Валидация скрипта
Заголовок раздела «Валидация скрипта»POST api/v1.1/integration/script/{ID скрипта}/validate
Запуск скрипта
Заголовок раздела «Запуск скрипта»POST api/v1.1/integration/script/{ID скрипта}/deploy
Создание операций
Заголовок раздела «Создание операций»Передача атрибутов
Заголовок раздела «Передача атрибутов»POST api/v1.1/integration/incomingOperation
Пример тела запроса:
{ "name":"Передача атрибутов", "folderId":"{{ID папки}}", "dataType":"ATTRIBUTES", "configurationId":"{{ID интеграционной конфигурации}}", "responseOperations":[], "requestScriptsSequence":[], "actionsSequence":[ { "id":"{{ID действия на авторизацию}}", "index":1 } ], "defaultResponseCode":"200", "defaultResponseMessage":"{\"result\":\"OK\"}"}Передача телеметрии
Заголовок раздела «Передача телеметрии»POST api/v1.1/integration/incomingOperation
Пример тела запроса:
{ "name":"Передача телеметрии", "folderId":"{{ID папки}}", "dataType":"TELEMETRY", "configurationId":"{{ID интеграционной конфигурации}}", "responseOperations":[], "requestScriptsSequence":[], "actionsSequence":[ { "id":"{{ID действия на авторизацию}}", "index":1 } ], "defaultResponseCode":"200", "defaultResponseMessage":"{\"result\":\"OK\"}"}Передача команд
Заголовок раздела «Передача команд»POST api/v1.1/integration/incomingOperation
Пример тела запроса:
{ "name":"Передача RPC-команд", "folderId":"{{ID папки}}", "dataType":"RPC", "configurationId":"{{ID интеграционной конфигурации}}", "responseOperations":[], "requestScriptsSequence":[], "actionsSequence":[ { "id":"{{ID действия на авторизацию}}", "index":1 }, { "id":"{{ID действия на извлечение request_id}}", "index":2 }, ], "defaultResponseCode":"200", "defaultResponseMessage":"{\"result\":\"OK\"}"}Если устройство получает сообщения от платформы в топик Kafka, предварительно необходимо выполнить подписку на соответствующий топик.
Подписка
Заголовок раздела «Подписка»POST api/v1.1/integration/incomingOperation
Пример тела запроса:
{ "name":"Подписка", "folderId":"{{ID папки}}", "dataType":"MIXED", "configurationId":"{{ID интеграционной конфигурации}}", "responseOperations":[], "requestScriptsSequence":[], "actionsSequence":[], "defaultResponseCode":"200", "defaultResponseMessage":"{\"result\":\"OK\"}"}Запуск входящих операций
Заголовок раздела «Запуск входящих операций»POST api/v1.1/integration/incomingOperation/{ID входящей операции}/deploy
Создание адреса подключения к платформе
Заголовок раздела «Создание адреса подключения к платформе»Передача атрибутов
Заголовок раздела «Передача атрибутов»POST api/v1.1/integration/incomingEndpoint
Пример тела запроса:
{ "name":"Передача атрибутов", "folderId":"{{ID папки}}", "type":"AUTH", // или COMMON "tenantType": "USER", "endpointConditions":[ { "conditionParameterType":"endpoint", // или mqttMessageType "comparisonOperation":"startsWith", // или equals "parameterName":"uriPath", // или name "expectedValue":"/api/v1" //или PUBLISH }, { "conditionParameterType":"endpoint", "comparisonOperation":"endsWith", // или equals "parameterName":"uriPath", // или topic "expectedValue":"/attributes" // или v1/devices/me/attributes }, { "conditionParameterType":"params", // объект не добавляется "comparisonOperation":"equals", "parameterName":"httpMethod", "expectedValue":"POST" } ], "incomingOperationId": "{{ID входящей операции на передачу атрибутов}}", "protocol":"HTTP" // или MQTT, COAP}В комментариях показан пример для MQTT.
Передача телеметрии
Заголовок раздела «Передача телеметрии»POST api/v1.1/integration/incomingEndpoint
Пример тела запроса:
{ "name":"Передача телеметрии", "folderId":"{{ID папки}}", "type":"AUTH", "tenantType": "USER", "endpointConditions":[ { "conditionParameterType":"endpoint", "comparisonOperation":"startsWith", "parameterName":"uriPath", "expectedValue":"/api/v1" }, { "conditionParameterType":"endpoint", "comparisonOperation":"endsWith", "parameterName":"uriPath", "expectedValue":"/telemetry" } { "conditionParameterType":"params", "comparisonOperation":"equals", "parameterName":"httpMethod", "expectedValue":"POST" } ], "incomingOperationId": "{{ID входящей операции на передачу телеметрии}}", "protocol":"HTTP"}Передача команд
Заголовок раздела «Передача команд»POST api/v1.1/integration/incomingEndpoint
Пример тела запроса:
{ "name":"Передача команд", "folderId":"{{ID папки}}", "type":"AUTH", "tenantType": "USER", "endpointConditions":[ { "conditionParameterType":"endpoint", "comparisonOperation":"startsWith", "parameterName":"uriPath", "expectedValue":"/api/v1" }, { "conditionParameterType":"endpoint", "comparisonOperation":"endsWith", "parameterName":"uriPath", "expectedValue":"/rpc" }, { "conditionParameterType":"params", "comparisonOperation":"equals", "parameterName":"httpMethod", "expectedValue":"POST" } ], "incomingOperationId": "{{ID входящей операции на передачу команд}}", "protocol":"HTTP"}Подписка
Заголовок раздела «Подписка»POST api/v1.1/integration/incomingEndpoint
Пример тела запроса:
{ "name":"Подписка на получение команд", "folderId":"{{ID папки}}", "type":"COMMON", "tenantType": "USER", "endpointConditions":[ { "conditionParameterType":"endpoint", // или mqttMessageType "comparisonOperation":"startsWith", // или equals "parameterName":"uriPath", // или name "expectedValue":"/api/v1" //или SUBSCRIBE }, { "conditionParameterType":"endpoint", // объект не добавляется "comparisonOperation":"endsWith", "parameterName":"uriPath", "expectedValue":"/attributes" }, { "conditionParameterType":"params", // объект не добавляется "comparisonOperation":"equals", "parameterName":"httpMethod", "expectedValue":"GET" } ], "incomingOperationId": "{{ID входящей операции на подписку}}", "protocol":"MQTT"}Запуск адреса подключения к платформе
Заголовок раздела «Запуск адреса подключения к платформе»POST api/v1.1/integration/incomingEndpoint/{ID адреса подключения к платформе}/deploy
Создание хоста для подключения к устройству
Заголовок раздела «Создание хоста для подключения к устройству»POST api/v1.1/integration/host
Пример тела запроса:
{ "folderId":"{{ID папки}}", "protocol":"HTTP", // или MQTT, COAP "host": null, // или {{хост}} "port": null, //или {{порт}} "connectionTimeout": 30000, "socketTimeout": 30000, "parameters":[]}В комментариях показан пример для MQTT.
Хост и порт указываются только в том случае, если сообщение нужно отправить в новое соединение
Создание адреса для подключения к устройству
Заголовок раздела «Создание адреса для подключения к устройству»Передача команд
Заголовок раздела «Передача команд»POST api/v1.1/integration/outgoingEndpoint
Пример тела запроса:
{ "folderId":"{{ID папки}}", "hostId":"{{ID хоста}}", "path":"v1/devices/me/rpc/request/{{externalRqId}}", "method":"PUBLISH", "urlEncoded":false}Передача запрошенных атрибутов
Заголовок раздела «Передача запрошенных атрибутов»POST api/v1.1/integration/incomingEndpoint
Пример тела запроса:
{ "folderId":"{{ID папки}}", "hostId":"{{ID хоста}}", "path":"v1/devices/me/attributes/response/{{externalRqId}}", "method":"PUBLISH", "urlEncoded":false}Создание исходящих операций
Заголовок раздела «Создание исходящих операций»Передача команд на устройство
Заголовок раздела «Передача команд на устройство»POST api/v1.1/integration/outgoingOperation
Пример тела запроса:
{ "name":"Получение команд", "folderId":"{{ID папки}}", "dataType":"RPC", "configurationId":"{{ID интеграционной конфигурации}}", "thingClassesRelation": [ { "classId": "{{classId устройства}}", "commandIds": [ "{{commandId класса}}" ] } ], "reuseConnection": true, "requestHostId": null, // или {{ID хоста}} "requestOutgoingEndpointId": null, // или {{ID исходящего эндпоинта на передачу команд}} "requestScriptsSequence":[ { "id":"{{ID скрипта на получение команд}}", "index":1 } ], "responseScriptsSequence":[], "actionsSequence":[], "errorResponseCodes":[], "successResponseCodes":[ "200", "201", "202", "203", "204" ], "syncRetryCodes":[], "syncRetryTimes":10, "asyncRetryTimes":5, "timeout":10000}Хост и исходящий эндпоинт указываются только в том случае, если сообщение нужно отправить в новое соединение.
Передача запрошенных атрибутов на устройство
Заголовок раздела «Передача запрошенных атрибутов на устройство»POST api/v1.1/integration/outgoingOperation
Пример тела запроса:
{ "name":"Передача запрошенных атрибутов", "folderId":"{{ID папки}}", "dataType":"ATTRIBUTES", "configurationId":"{{ID интеграционной конфигурации}}", "thingClassesRelation": [ { "classId": "{{classId устройства}}", "commandIds": [ "{{commandId класса}}" ] } ], "reuseConnection": true, "requestHostId": null, // или {{ID хоста}} "requestOutgoingEndpointId": null, // или {{ID исходящего эндпоинта на передачу запрошенных атрибутов}} "requestScriptsSequence":[ { "id":"{{ID скрипта на получение запрошенных атрибутов}}", "index":1 } ], "responseScriptsSequence":[], "actionsSequence":[], "errorResponseCodes":[], "successResponseCodes":[ "200", "201", "202", "203", "204" ], "syncRetryCodes":[], "syncRetryTimes":10, "asyncRetryTimes":5, "timeout":10000}