Информация о состояниях устройств пользователя
Запрашивает информацию о текущем состоянии устройств пользователя.
Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение Дом с Алисой и хочет поменять состояние устройств.
В ответ на такой запрос провайдеру необходимо вернуть состояния запрошенных устройств пользователя.
Примечание
Умения, для которых запрос состояния недоступен (имеющие атрибут retrievable=false
), можно не включать в ответ, так как их состояние будет проигнорировано.
Формат запроса платформы умного дома
Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).
POST https://example.com/v1.0/user/devices/query
Заголовки запроса
Заголовок |
Описание |
Обязательный |
Authorization |
Авторизационный токен владельца навыка. |
Да |
Content-Type |
Формат передаваемых/отправляемых данных. Возможные значения: application/json. |
Да, в операциях с http-методом POST |
X-Request-Id |
Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. |
Да |
Формат тела запроса
{
"devices": [
{
"id": String,
"custom_data": Object
},
...
]
}
Параметр |
Тип |
Описание |
Обязательный |
devices |
Array of objects |
Массив с устройствами пользователя. |
Да |
Объект devices
Параметр |
Тип |
Описание |
Обязательный |
id |
String |
Идентификатор устройства. Должен быть уникален среди всех устройств производителя. |
Да |
custom_data |
Object |
Объект, который был передан провайдером для устройства в ответе на запрос Информация об устройствах пользователя. |
Нет |
Формат ответа провайдера
Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.
HTTP/1.1 200 OK
{
"request_id": String,
"payload": {
"devices":[
{
"id": String,
"capabilities": [
"<capability1>": Object,
"<capability2>": Object,
...
],
"properties": [
"<property1>": Object,
"<property2>": Object,
...
],
"error_code": String,
"error_message": String
},
...
]
}
}
Параметр |
Тип |
Описание |
Обязательный |
request_id |
String |
Идентификатор запроса. |
Да |
payload |
Object |
Объект с устройствами. |
Да |
Объект payload
Параметр |
Тип |
Описание |
Обязательный |
devices |
Array of objects |
Массив с устройствами пользователя. |
Да |
Объект devices
Параметр |
Тип |
Описание |
Обязательный |
id |
String |
Идентификатор устройства. Должен быть уникален среди всех устройств производителя. |
Да |
capabilities |
Array of objects |
Массив с информацией об умениях устройства. |
Нет |
properties |
Array of objects |
Массив с информацией о свойствах устройства. |
Нет |
error_code |
String |
Код возможной ошибки из списка. Если поле непустое, параметры |
Нет |
error_message |
String |
Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование. |
Нет |
Объект capabilities
Параметр |
Тип |
Описание |
Обязательный |
<capability1> |
Object |
Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Нет |
<capability2> |
Object |
Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Нет |
Объект properties
Параметр |
Тип |
Описание |
Обязательный |
<property1> |
Object |
Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах. |
Нет |
<property2> |
Object |
Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах. |
Нет |
HTTP/1.1 404 Not Found
Пример
В примере описаны свойства светильника с регулировкой цвета и розетки.
ЗапросУспешный ответОтвет с ошибкой
curl -i -X POST 'https://example.com/v1.0/user/devices/query' \ -H 'Authorization: Bearer 123qwe456a...' \ -H 'X-Request-Id: ff36a3cc-ec...' \ -H 'Content-Type: application/json'
Тело запроса
{ "devices": [ { "id": "abc-123", "custom_data": { "foo": 1, "bar": "two", "baz": false, "qux": [1, "two", false], "quux": { "quuz": { "corge": [] } } } }, { "id": "sock-56GF-3" } ] }
{ "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": [{ "id": "abc-123", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "hsv", "value": { "h": 255, "s": 50, "v": 100 } } }, { "type": "devices.capabilities.on_off", "state": { "instance": "on", "value": true } }] }, { "id": "abc-123", "error_code": "DEVICE_NOT_FOUND", "error_message": "the human readable error message" }, { "id": "sock-56GF-3", "capabilities": [{ "type": "devices.capabilities.on_off", "state": { "instance": "on", "value": true } }] }] } }
HTTP/1.1 404 Not Found
Список пар "ключ": значение
, разделенных запятой. Выделяется фигурными скобками {}
.
{
"name": "John",
"surname": "Smith"
}
Cтрока, выделяется кавычками, например "Hello world"
.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]