Перейти к содержимому

Подключение при помощи Management API

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

Шаги настройки:

  1. Создайте общую папку
  2. Создайте интеграционную конфигурацию
  3. Запустите интеграционную конфигурацию
  4. Создайте действия (actions)
  5. Создайте скрипт на получение команд
  6. Осуществите валидацию скрипта
  7. Запустите скрипт
  8. Создайте операции
  9. Запустите входящие операции
  10. Создайте адреса подключения (endpoints) к платформе
  11. Запустите адреса подключения к платформе
  12. Создайте хост для подключения к устройству
  13. Создайте адрес для подключения к устройству
  14. Создайте исходящую операцию

POST api/v1.1/integration/folder

Пример тела запроса:

json
{
"name":"Папка для конфигураций"
}

POST api/v1.1/integration/configuration

Пример тела запроса:

json
{
"name":"Интеграционная конфигурация",
"folderId":"{{ID папки}}",
"logLevel":"Error",
"errorItemIds":[],
"defaultTimeout":30000
}

POST api/v1.1/integration/сonfiguration/{ID интеграционной конфигурации}/deploy

POST api/v1.1/integration/action

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"folderId":"{{ID папки}}",
"protocol":"HTTP", // или MQTT, COAP
"host": null, // или {{хост}}
"port": null, //или {{порт}}
"connectionTimeout": 30000,
"socketTimeout": 30000,
"parameters":[]
}

В комментариях показан пример для MQTT.

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

Создание адреса для подключения к устройству

Заголовок раздела «Создание адреса для подключения к устройству»

POST api/v1.1/integration/outgoingEndpoint

Пример тела запроса:

json
{
"folderId":"{{ID папки}}",
"hostId":"{{ID хоста}}",
"path":"v1/devices/me/rpc/request/{{externalRqId}}",
"method":"PUBLISH",
"urlEncoded":false
}

POST api/v1.1/integration/incomingEndpoint

Пример тела запроса:

json
{
"folderId":"{{ID папки}}",
"hostId":"{{ID хоста}}",
"path":"v1/devices/me/attributes/response/{{externalRqId}}",
"method":"PUBLISH",
"urlEncoded":false
}

POST api/v1.1/integration/outgoingOperation

Пример тела запроса:

json
{
"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

Пример тела запроса:

json
{
"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
}