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

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

HTTP Device API ​

Примечание

Во всех запросах используется PATH-параметр $ACCESS_TOKEN. При вызове любого метода вместо $ACCESS_TOKEN необходимо подставить значение токена, полученного на шаге создания устройства (содержится в поле "token", например generatedToken-e53d7b39-11c8-4ae4-8363-474df9325262).

Передача телеметрии в платформу ​

POST http://host:port/api/v1/$ACCESS_TOKEN/telemetry

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

JSON
{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Формат сообщений, поддерживаемый платформой при передачи телеметрии от устройства:

  • {"key1":"value1", "key2":"value2"}
    или
  • [{"key1":"value1"}, {"key2":"value2"}]
    или
  • {"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

Передача атрибутов в платформу ​

POST http://host:port/api/v1/$ACCESS_TOKEN/attributes

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

JSON
{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Запросить атрибуты с платформы ​

GET http://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Пример ответа:

JSON
{
   "client":{
      "attribute1":"value1",
      "attribute2":true
   }
}

Подписка на обновление атрибутов с платформы ​

GET http://host:port/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Пример ответа:

JSON
{
   "client":{
      "attribute1":"value1",
      "attribute2":true
   }
}

Подписка на команды от платформы ​

GET http://host:port/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

Пример ответа:

JSON
{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

где:

  • id - request id, integer request identifier
  • method - RPC method name, string
  • params - RPC method params, custom json object

Для ответа устройство должно использовать метод POST http://host:port/api/v1/$ACCESS_TOKEN/rpc/$id, где $id - идентификатор из запроса выше. Тело запроса:

JSON
{
   "result":"ok"
}

Отправка команд на платформу ​

POST http://host:port/api/v1/$ACCESS_TOKEN/rpc

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

JSON
{
   "method":"getCurrentTime",
   "params":{
      
   }
}

Пример ответа:

JSON
{
   "time":"2016 11 21 12:54:44.287"
}

COAP Device API ​

Примечание

Во всех запросах используется PATH-параметр $ACCESS_TOKEN. При вызове любого метода вместо $ACCESS_TOKEN необходимо подставить значение токена, полученного на шаге создания устройства (содержится в поле "token", например generatedToken-e53d7b39-11c8-4ae4-8363-474df9325262).

Передача телеметрии в платформу ​

POST coap://host/api/v1/$ACCESS_TOKEN/telemetry

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

JSON
{
    "ts": 1451649600512,
    "values": {
        "stringKey": "value1",
        "booleanKey": true,
        "doubleKey": 42.0,
        "longKey": 73,
        "jsonKey": {
            "someNumber": 42,
            "someArray": [
                1,
                2,
                3
            ],
            "someNestedObject": {
                "key": "value"
            }
        }
    }
}

Формат сообщений, поддерживаемый платформой при передачи телеметрии от устройства:

JSON
{
    "key1": "value1",
    "key2": "value2"
}

или

JSON
[
    {
        "key1": "value1"
    },
    {
        "key2": "value2"
    }
]

Передача атрибутов в платформу ​

POST coap://host/api/v1/$ACCESS_TOKEN/attributes

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

JSON
{
    "attribute1": "value1",
    "attribute2": true,
    "attribute3": 42.0,
    "attribute4": 73,
    "attribute5": {
        "someNumber": 42,
        "someArray": [
            1,
            2,
            3
        ],
        "someNestedObject": {
            "key": "value"
        }
    }
}

Запросить атрибуты с платформы ​

GET coap://host/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Пример ответа:

JSON
{
    "client": {
        "attribute1": "value1",
        "attribute2": true
    }
}

Подписка на обновление атрибутов с платформы ​

GET coap://host/api/v1/$ACCESS_TOKEN/attributes с флагом Observe

Пример ответа:

JSON
{
    "client": {
        "attribute1": "value1",
        "attribute2": true
    }
}

Подписка на команды от платформы ​

GET coap://host/api/v1/$ACCESS_TOKEN/rpc с флагом Observe

Пример ответа:

JSON
{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

где:

  • id - request id, integer request identifier
  • method - RPC method name, string
  • params - RPC method params, custom json object

Для ответа устройство должно использовать метод POST coap://host:port/api/v1/$ACCESS_TOKEN/rpc/$id, где $id - идентификатор из запроса выше. Тело запроса:

JSON
{
   "result":"ok"
}

Отправка команд на платформу ​

POST coap://host/api/v1/$ACCESS_TOKEN/rpc

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

JSON
{
   "method":"getCurrentTime",
   "params":{
      
   }
}

Пример ответа:

JSON
{
   "time":"2016 11 21 12:54:44.287"
}

MQTT Device API ​

При помощи MQTT Device API обеспечивается возможность передавать запросы от сторонних коннекторов (устройств, присоединенных по различным протоколам) в IoT платформу.

Авторизация ​

Для авторизации необходимо отправить сообщение типа MQTT connect с указанием в payload следующих данных:

Пример кода на JS:

js
import org.eclipse.paho.client.mqttv3.*;
public class App {
    public static void main(String[] args) throws Exception {
      // client, user and device details
        final String serverUrl = "tcp://mqtt.mts.ru"; // пример значения  
        final String username = "$ACCESS_TOKEN"; // пример значения
        // MQTT connection options
        final MqttConnectOptions options = new MqttConnectOptions();
        options.setUserName(username);
      // connect the client to platform
        final MqttClient client = new MqttClient(serverUrl);
        client.connect(options);
    }
     
}

В примере выше для $ACCESS_TOKEN необходимо подставить значение токена, полученного на шаге создания устройства (содержится в поле "token", например generatedToken-e53d7b39-11c8-4ae4-8363-474df9325262).

Передача телеметрии в платформу ​

  • Path: v1/devices/me/telemetry
  • Описание: отправка телеметрии от устройств

Чтобы устройство могло передавать на платформу значения собираемой телеметрии, необходимо:

  1. убедиться что сервис, после успешной авторизации устройства, может принимать телеметрию в MQQT-топик v1/devices/me/telemetry;
  2. проверить корректность формата;
  3. дополнить временной меткой (timestamp), если она не передана;
  4. передать сообщение в kafka брокер, топик NETWORK.TOPIC.TELEMETRY.IN.

Ожидаемые форматы сообщений:

JSON
{
  "ts": 1451649600512,
  "values": [{"key1":"value1"}, {"key2":"value2"}]
}

или

JSON
{
  "ts": 1451649600512,
  "values": {"key1":"value1", "key2":"value2"}
}

В случае, если не передан timestamp (поле ts), необходимо дополнить JSON:

JSON
{
  "ts": <ts значение в UNIX EPOCH формате>,
  "values": {"key1":"value1", "key2":"value2"}
}

Обновление атрибутов устройств ​

  • Path: v1/devices/me/attributes
  • Описание: отправка обновлений атрибутов устройств

Чтобы устройство могло передавать на платформу значения собственных атрибутов, необходимо:

  1. убедиться что сервис, после успешной авторизации устройства, может принимать телеметрию в MQQT-топик v1/devices/me/attributes;
  2. проверить корректность формата;
  3. передать сообщение в Kafka брокер, топик NETWORK.TOPIC.ATTRIBUTES.IN.

Ожидаемые форматы сообщений:

JSON
{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}