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

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

Примечание.

После связи аккаунтов провайдера и Яндекса также отправляется данный запрос.

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

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

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

Получив реплику пользователя (голосовой помощник Алиса) или действие пользователя (ПП), платформа умного дома отправляет запрос на Endpoint URL провайдера (endpoint_url).

GET https://endpoint_url/v1.0/user/devices

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

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

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

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

{
  "request_id": String,
  "payload": {
      "user_id": String,
      "devices": [
        {
          "id": String,
          "name": String,
          "description": String,
          "room": String,
          "type": String,
          "custom_data": Object,
          "capabilities": [
            "<capability1>": Object,
            "<capability2>": Object,
            ...
          ],
          "device_info": {
            "manufacturer": String,
            "model": String,
            "hw_version": String,
            "sw_version": String
          }
        },
        ...
      ]
  }
}
request_id *
Идентификатор запроса.
payload
Объект с ответом на запрос.
user_id *
Идентификатор пользователя.
devices *
Массив с устройствами пользователя.
id *
Идентификатор устройства.
name
Название устройства.
description
Описание устройства.
room
Название помещения, в котором расположено устройство.
type *
Тип устройства. Со списком типов устройств можно ознакомиться в разделе Устройство (device).
custom_data

Любой валидный объект. Состоит из набора пар "ключ":"значение" любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт.

capabilities *
Массив с информацией об умениях устройства.
<capability1>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).
<capability2>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).
device_info
Дополнительная техническая информация об устройстве.
manufacturer
Производитель устройства.
model
Модель устройства.
hw_version
Версия аппаратной составляющей устройства.
sw_version
Версия программного обеспечения.

Обязательный параметр

Пример

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

Запрос
curl -i -X GET 'https://endpoint_url/v1.0/user/devices' -H 'Authorization: Bearer 123qwe456a...' -H 'X-Request-Id: ff36a3cc-ec...'
Успешный ответ
HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "user_id": "Misha-01-super-545",
        "devices": [{
                "id": "abc-123",
                "name": "лампa",
                "description": "цветная лампа",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                  "foo": 1,
                  "bar": "two",
                  "baz": false,
                  "qux": [1, "two", false],
                  "quux": {
                    "quuz": {
                      "corge": []
                    }
                  }
                },
                "capabilities": [{
                        "type": "devices.capabilities.range",
                        "retrievable": true,
                        "parameters": {
                            "instance": "brightness",
                            "unit": "unit.percent",
                            "range": {
                                "min": 0,
                                "max": 100,
                                "precision": 10
                            }
                        }
                    },
                    {
                        "type": "devices.capabilities.on_off"
                    },
                    {
                        "type": "devices.capabilities.color_setting",
                        "parameters": {
                            "color_model": "hsv",
                            "temperature_k": {
                                "min": 2700,
                                "max": 9000,
                                "precision": 1
                            }
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider2",
                    "model": "hue g11",
                    "hw_version": "1.2",
                    "sw_version": "5.4"
                }
            }
          }
        ]
    }
}
Ответ с ошибкой
HTTP/1.1 401 Unauthorized