Изменение состояния у устройств
Изменяет текущее состояние устройств пользователя.
Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение Дом с Алисой и хочет поменять состояние устройств.
В ответ на такой запрос провайдеру необходимо изменить состояния запрошенных устройств пользователя.
Формат запроса платформы умного дома
Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).
POST https://example.com/v1.0/user/devices/action
Заголовки запроса
Заголовок | Описание | Обязательный |
---|---|---|
Authorization | Авторизационный токен пользователя. | Да |
Content-Type | Формат передаваемых/отправляемых данных. Возможные значения: application/json. | Да, в операциях с http-методом POST |
X-Request-Id | Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. | Да |
Заголовок | Описание | Обязательный |
---|---|---|
Authorization | Авторизационный токен пользователя. | Да |
Content-Type | Формат передаваемых/отправляемых данных. Возможные значения: application/json. | Да, в операциях с http-методом POST |
X-Request-Id | Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. | Да |
Формат тела запроса
{
"payload": {
"devices":[
{
"id": String,
"custom_data": Object,
"capabilities": [
"<capability1>": Object,
"<capability2>": Object,
...
]
}
]
}
}
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
payload | Object | Объект с устройствами. | Да |
Объект payload | |||
devices | Array of objects | Массив с устройствами пользователя. | Да |
Объект devices | |||
id | String | Идентификатор устройства. Должен быть уникален среди всех устройств производителя. | Да |
custom_data | Object | Объект, который провайдер прислал вместе с устройством в ответ на запрос Информация об устройствах пользователя. Состоит из набора пар "ключ":"значение" любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. | Нет |
capabilities | Array of objects | Массив с информацией об умениях устройства. | Да |
Объект capabilities | |||
<capability1> | Object | Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Да |
<capability2> | Object | Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Да |
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
payload | Object | Объект с устройствами. | Да |
Объект payload | |||
devices | Array of objects | Массив с устройствами пользователя. | Да |
Объект devices | |||
id | String | Идентификатор устройства. Должен быть уникален среди всех устройств производителя. | Да |
custom_data | Object | Объект, который провайдер прислал вместе с устройством в ответ на запрос Информация об устройствах пользователя. Состоит из набора пар "ключ":"значение" любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. | Нет |
capabilities | Array of objects | Массив с информацией об умениях устройства. | Да |
Объект capabilities | |||
<capability1> | Object | Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Да |
<capability2> | Object | Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Да |
Формат ответа провайдера
Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.
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 |
action_result | Object | Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует Примечание. Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства. Ответ на запрос считается успешным ( | Да, если отсутствует capabilities |
Объект capabilities | |||
<capability1> | Object | Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Нет |
<capability2> | Object | Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Нет |
Объект action_result | |||
status | String | Статус изменения состояния у устройства. Допустимые значения:
| Нет |
error_code | String | Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. | Нет |
error_message | String | Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование . | Нет |
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
request_id | String | Идентификатор запроса. | Да |
payload | Object | Объект с устройствами. | Да |
Объект payload | |||
devices | Array of objects | Массив с устройствами пользователя. | Да |
Объект devices | |||
id | String | Идентификатор устройства. Должен быть уникален среди всех устройств производителя. | Да |
capabilities | Array of objects | Массив с информацией об умениях устройства. | Да, если отсутствует action_result |
action_result | Object | Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует Примечание. Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства. Ответ на запрос считается успешным ( | Да, если отсутствует capabilities |
Объект capabilities | |||
<capability1> | Object | Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Нет |
<capability2> | Object | Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. | Нет |
Объект action_result | |||
status | String | Статус изменения состояния у устройства. Допустимые значения:
| Нет |
error_code | String | Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. | Нет |
error_message | String | Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование . | Нет |
HTTP/1.1 404 Not Found
Пример
curl -i -X POST 'https://example.com/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'
Тело запроса
{
"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
}
}]
}]
}
}
HTTP/1.1 200 OK
{
"request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3",
"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