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

Запрашивает информацию о поддерживаемых устройствах пользователя.

Платформа умного дома отправит провайдеру текущий запрос при выполнении условий:

  • Аккаунты на Яндексе и на стороне провайдера связаны.
  • Пользователь зашел в приложение Дом с Алисой → plus Created with Sketch.  → Устройство умного дома и напротив названия производителя нажал кнопку Обновить.

Примечание

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

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

Если часть устройств недоступна и провайдер не смог отправить информацию о них, платформа умного дома оставит эти устройства пользователя без изменений. Удалить устройство из списка может только сам пользователь.

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

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

GET https://example.com/v1.0/user/devices

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

Заголовок

Описание

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

Authorization

Авторизационный токен владельца навыка.

Да

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,
            ...
          ],
          "properties": [
            "<property1>": Object,
            "<property2>": Object,
            ...
          ],
          "device_info": {
            "manufacturer": String,
            "model": String,
            "hw_version": String,
            "sw_version": String
          }
        },
        ...
      ]
  }
}

Параметр

Тип

Описание

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

request_id

String

Идентификатор запроса.

Да

payload

Object

Объект с устройствами.

Да

Объект payload

Параметр

Тип

Описание

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

user_id

String

Идентификатор пользователя.

Да

devices

Array of objects

Массив с устройствами пользователя.

Да

Объект devices

Параметр

Тип

Описание

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

id

String

Идентификатор устройства. Должен быть уникален среди всех устройств производителя.

Да

name

String

Название устройства.

Да

description

String

Описание устройства.

Нет

room

String

Название помещения, в котором расположено устройство.

Нет

type

String

Тип устройства. Со списком типов устройств можно ознакомиться в разделе Типы устройств.

Да

custom_data

Object

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

Нет

capabilities

Array of objects

Массив с информацией об умениях устройства.

Да, если отсутствует properties

properties

Array of objects

Массив с информацией о свойствах устройства.

Да, если отсутствует capabilities

device_info

Object

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

Да, для официальных навыков

Объект capabilities

Параметр

Тип

Описание

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

<capability1>

Object

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

Нет

<capability1>

Object

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

Нет

Объект properties

Параметр

Тип

Описание

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

<property1>

Object

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

Нет

<property2>

Object

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

Нет

Объект device_info

Параметр

Тип

Описание

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

manufacturer

String

Название производителя устройства. Может содержать до 256 символов. Параметр является обязательным для описания официального навыка (подробнее в разделе Об умном доме).

Да, для официальных навыков

model

String

Название модели устройства. Может содержать до 256 символов.Параметр является обязательным для описания официального навыка (подробнее в разделе Об умном доме).

Да, для официальных навыков

hw_version

String

Версия аппаратной составляющей устройства. Может содержать до 256 символов.

Нет

sw_version

String

Версия программного обеспечения устройства. Может содержать до 256 символов.

Нет

 
HTTP/1.1 404 Not Found

Глобальные коды

Пример

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

curl -i -X GET 'https://example.com/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

Предыдущая
Оповещение о разъединении аккаунтов
Следующая
Информация о состояниях устройств пользователя