Информация об устройствах пользователя
Запрашивает информацию о поддерживаемых устройствах пользователя.
Если пользователь зашел в и нажал кнопку Обновить список устройств , платформа умного дома отправит провайдеру текущий запрос (при условии того, что аккаунты провайдера и Яндекса связаны).
Примечание.
После связи аккаунтов провайдера и Яндекса также отправляется данный запрос.
В ответ на такой запрос провайдеру необходимо вернуть список всех поддерживаемых устройств пользователя с описанием доступных умений и встроенных датчиков. Максимальное количество устройств пользователя — 301.
Если часть устройств недоступна и провайдер не смог отправить информацию о них, платформа умного дома оставит эти устройства пользователя без изменений. Удалить устройство из списка может только сам пользователь.
Формат запроса платформы умного дома
Платформа умного дома отправляет запрос на 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 символов. | Нет |
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