Информация о состояниях устройств пользователя
Запрашивает информацию о текущем состоянии устройств пользователя.
Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение Дом с Алисой и хочет поменять состояние устройств.
В ответ на такой запрос провайдеру необходимо вернуть состояния запрошенных устройств пользователя.
Примечание
Умения, для которых запрос состояния недоступен (имеющие атрибут retrievable=false
), можно не включать в ответ, так как их состояние будет проигнорировано.
Формат запроса платформы умного дома
Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).
POST https://functions.yandexcloud.net/<function_id>?integration=raw
Формат тела запроса
{
"headers": {
"request_id": String,
"authorization": String
},
"request_type": String,
"payload": {
"devices": [
{
"id": String,
"custom_data": Object
},
...
]
},
"api_version": Float
}
Параметр |
Тип |
Описание |
Обязательный |
headers |
Object |
Объект с дополнительными полями запроса. |
Да |
request_type |
String |
Тип запроса. Допустимые значения:
|
Да |
payload |
Object |
Объект с устройствами. |
Да |
api_version |
Float |
Версия протокола Умного дома. |
Да |
Объект headers
Параметр |
Тип |
Описание |
Обязательный |
request_id |
String |
Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. |
Да |
authorization |
String |
Авторизационный токен пользователя. |
Да |
Объект payload
Параметр |
Тип |
Описание |
Обязательный |
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 |
Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах. |
Нет |
Подробнее о том, как отдавать коды состояния, отличные от 200 OK
, читайте в документации.
HTTP/1.1 404 Not Found
Пример
В примере описаны свойства светильника с регулировкой цвета и розетки.
ЗапросУспешный ответОтвет с ошибкой
curl -i POST https://functions.yandexcloud.net/<function_id>?integration=raw \ -H 'Content-Type: application/json' \ -d '{ "headers": { "request_id": "1111-aaaa-2222-bbbb", "authorization": "Bearer 123qwe456a..." }, "request_type": "query", "payload": { "devices": [{ "id": "abc-123", "custom_data": { "foo": 1, "bar": "two", "baz": false, "qux": [1, "two", false], "quux": { "quuz": { "corge": [] } } } }, { "id": "sock-56GF-3" } ]}, "api_version": 1.0 }'
{ "request_id": "1111-aaaa-2222-bbbb", "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"
.
Число с плавающей точкой с точностью до 6-9 десятичных знаков.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]