Изменение состояния у устройств
Изменяет текущее состояние устройств пользователя.
Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение Дом с Алисой и хочет поменять состояние устройств.
В ответ на такой запрос провайдеру необходимо изменить состояния запрошенных устройств пользователя.
Формат запроса платформы умного дома
Платформа умного дома отправляет запрос на 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,
"capabilities": [
"<capability1>": Object,
"<capability2>": 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 |
Объект, который провайдер прислал вместе с устройством в ответ на запрос Информация об устройствах пользователя. Состоит из набора пар |
Нет |
capabilities |
Array of objects |
Массив с информацией об умениях устройства. |
Да |
Объект capabilities
Параметр |
Тип |
Описание |
Обязательный |
<capability1> |
Object |
Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Да |
<capability2> |
Object |
Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Да |
Формат ответа провайдера
Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.
Подробнее о том, как отдавать коды состояния, отличные от 200 OK
, читайте в документации.
HTTP/1.1 200 OK
{
"request_id": String,
"payload": {
"devices": [
{
"id": String,
"capabilities": [
"<capability1>": Object,
"<capability2>": Object,
...
],
"action_result": {
"status": String,
"error_code": String,
"error_message": String
}
},
...
]
}
}
Параметр |
Тип |
Описание |
Обязательный |
request_id |
String |
Идентификатор запроса. |
Да |
payload |
Object |
Объект с устройствами. |
Да |
Объект payload
Параметр |
Тип |
Описание |
Обязательный |
devices |
Array of objects |
Массив с устройствами пользователя. |
Да |
Объект devices
Параметр |
Тип |
Описание |
Обязательный |
id |
String |
Идентификатор устройства. Должен быть уникален среди всех устройств производителя. |
Да |
capabilities |
Array of objects |
Массив с информацией об умениях устройства. |
Да, если отсутствует |
action_result |
Object |
Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует Примечание Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства. Ответ на запрос считается успешным ( |
Да, если отсутствует |
Объект capabilities
Параметр |
Тип |
Описание |
Обязательный |
<capability1> |
Object |
Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Нет |
<capability2> |
Object |
Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. |
Нет |
Объект action_result
Параметр |
Тип |
Описание |
Обязательный |
status |
String |
Статус изменения состояния у устройства. Допустимые значения:
|
Нет |
error_code |
String |
Код возможной ошибки из списка. Если поле непустое, параметры |
Нет |
error_message |
String |
Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование. |
Нет |
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": "action", "payload": { "devices": [{ "id": "abc-123", "custom_data": { "foo": 1, "bar": "two", "baz": false, "qux": [1, "two", false], "quux": { "quuz": { "corge": [] } } }, "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": false } } ] }, { "id": "sock-56GF-3", "capabilities": [{ "type": "devices.capabilities.on_off", "state": { "instance": "on", "value": false } }] }] }, "api_version": 1.0 }'
HTTP/1.1 200 OK { "request_id": "1111-aaaa-2222-bbbb", "payload": { "devices": [{ "id": "abc-123", "capabilities": [{ "type": "devices.capabilities.color_setting", "state": { "instance": "hsv", "action_result": { "status": "ERROR", "error_code": "INVALID_ACTION", "error_message": "the human readable error message" } } }, { "type": "devices.capabilities.on_off", "state": { "instance": "on", "action_result": { "status": "DONE" } } }] }, { "id": "sock-56GF-3", "action_result": { "status": "ERROR", "error_code": "DEVICE_UNREACHABLE" } }] } }
HTTP/1.1 404 Not Found
Часто задаваемые вопросы
Можно ли настроить оповещения об изменениях в состоянии устройств?
Для таких оповещений необходим асинхронный протокол. Он не используется в Диалогах.
Список пар "ключ": значение
, разделенных запятой. Выделяется фигурными скобками {}
.
{
"name": "John",
"surname": "Smith"
}
Cтрока, выделяется кавычками, например "Hello world"
.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]
Число с плавающей точкой с точностью до 6-9 десятичных знаков.