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

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

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

Примечание.

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

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

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

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

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

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

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

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

Заголовок Описание Обязательный
Authorization Авторизационный токен пользователя. Да
X-Request-Id Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. Да
Заголовок Описание Обязательный
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 Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
<capability2> Object Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
Объект properties
<property1> Object Описание встроенного датчика. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
<property2> Object Описание встроенного датчика. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
Объект device_info
manufacturer String Название производителя устройства. Может содержать до 256 символов. Параметр является обязательным для описания официального навыка (подробнее в разделе Общие сведения). Да, для официальных навыков
model String Название модели устройства. Может содержать до 256 символов.Параметр является обязательным для описания официального навыка (подробнее в разделе Общие сведения). Да, для официальных навыков
hw_version String Версия аппаратной составляющей устройства. Может содержать до 256 символов. Нет
sw_version String Версия программного обеспечения устройства. Может содержать до 256 символов. Нет
Параметр Тип Описание Обязательный
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 Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
<capability2> Object Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. Нет
Объект properties
<property1> Object Описание встроенного датчика. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
<property2> Object Описание встроенного датчика. Подробнее со списком доступных встроенных датчиков и их параметрами можно ознакомиться в разделе Встроенные датчики. Нет
Объект device_info
manufacturer String Название производителя устройства. Может содержать до 256 символов. Параметр является обязательным для описания официального навыка (подробнее в разделе Общие сведения). Да, для официальных навыков
model String Название модели устройства. Может содержать до 256 символов.Параметр является обязательным для описания официального навыка (подробнее в разделе Общие сведения). Да, для официальных навыков
hw_version String Версия аппаратной составляющей устройства. Может содержать до 256 символов. Нет
sw_version String Версия программного обеспечения устройства. Может содержать до 256 символов. Нет

Пример

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

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'