Информация об устройствах пользователя
Запрашивает информацию о поддерживаемых устройствах пользователя.
Платформа умного дома отправит провайдеру текущий запрос при выполнении условий:
- Аккаунты на Яндексе и на стороне провайдера связаны.
- Пользователь зашел в приложение Дом с Алисой → → Устройство умного дома и напротив названия производителя нажал кнопку Обновить.
Примечание
После связки аккаунтов на Яндексе и на стороне провайдера также отправляется данный запрос.
В ответ на такой запрос провайдеру необходимо вернуть список всех поддерживаемых устройств пользователя с описанием доступных умений и свойств. Максимальное количество устройств пользователя — 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 |
Объект, который состоит из набора пар |
Нет |
capabilities |
Array of objects |
Массив с информацией об умениях устройства. |
Да, если отсутствует |
properties |
Array of objects |
Массив с информацией о свойствах устройства. |
Да, если отсутствует |
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
Список пар "ключ": значение
, разделенных запятой. Выделяется фигурными скобками {}
.
{
"name": "John",
"surname": "Smith"
}
Cтрока, выделяется кавычками, например "Hello world"
.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]