Информация о состояниях устройств пользователя

Запрашивает информацию о текущем состоянии устройств пользователя.

Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в ПП (поисковое приложения Яндекса) в раздел с устройствами, платформа умного дома отправит провайдеру текущий запрос.

В ответ на такой запрос провайдеру необходимо вернуть состояния запрошенных устройств пользователя.

Примечание.

Умения, для которых запрос состояния недоступен (имеющие атрибут retrievable=false), можно не включать в ответ, так как их состояние будет проигнорировано.

  1. Формат запроса платформы умного дома
  2. Формат ответа провайдера
  3. Пример

Формат запроса платформы умного дома

Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).

POST https://example.com/v1.0/user/devices/query

Заголовки запроса

Заголовок Описание Обязательный
Authorization Авторизационный токен пользователя. Да
Content-Type Формат передаваемых/отправляемых данных. Возможные значения: application/json. Да, в операциях с http-методом POST
X-Request-Id Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. Да
Заголовок Описание Обязательный
Authorization Авторизационный токен пользователя. Да
Content-Type Формат передаваемых/отправляемых данных. Возможные значения: application/json. Да, в операциях с http-методом POST
X-Request-Id Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. Да

Формат тела запроса

{
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
}
Параметр Тип Описание Обязательный
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Да
custom_data Object Объект, который был передан провайдером для устройства в ответе на запросИнформация об устройствах пользователя. Нет
Параметр Тип Описание Обязательный
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Да
custom_data Object Объект, который был передан провайдером для устройства в ответе на запросИнформация об устройствах пользователя. Нет

Формат ответа провайдера

Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.

HTTP/1.1 200 OK

{
  "request_id": String,
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1": Object,
          "<capability2>": Object,
          ...
        ],
        "properties": [
          "<property1>": Object,
          "<property2>": Object,
          ...
        ],
        "error_code": String,
        "error_message": String
      },
      ...
    ]  
  }
}
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Да
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Да
capabilities Array of objects Массив с информацией об умениях устройства. Нет
properties Array of objects Массив с информацией о встроенных датчиках устройства. Нет
error_code String Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование. Нет
Объект capabilities
<capability1> Object Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
<capability2> Object Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
Объект properties
<property1> Object Встроенный датчик и его статус. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
<property2> Object Встроенный датчик и его статус. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Да
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Да
capabilities Array of objects Массив с информацией об умениях устройства. Нет
properties Array of objects Массив с информацией о встроенных датчиках устройства. Нет
error_code String Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование. Нет
Объект capabilities
<capability1> Object Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
<capability2> Object Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
Объект properties
<property1> Object Встроенный датчик и его статус. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
<property2> Object Встроенный датчик и его статус. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет

Коды, связанные с запросом

Пример

В примере описаны свойства светильника с регулировкой цвета и розетки.

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Тело запроса

{
    "devices": [
        {
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            } 
        },
        {
            "id": "sock-56GF-3" 
        }   
    ]
}