Вернуться наверх
На этой странице:

Подключение при помощи 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

Создание действий (actions) ​

Действие на авторизацию ​

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 из входящего запроса ​

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
}