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