Запрос изменения состояния устройства (post command)
Умный дом Sber отправляет вендору запрос на изменение состояния устройства.
Пример ситуации использования:
- Пользователь в приложении Салют, на SberPortal, SberBox или другом устройстве с ассистентами Салют изменяет состояние лампы, например, выключает ее.
- Умный дом отправляет вендору запрос на изменение состояния лампы.
- Вендор получает запрос и отправляет на лампу команду выключения. Лампа пользователя гаснет.
Формат запроса
Умный дом Sber отправляет запрос на эндпоинт вендора. Заголовки см. в разделе Заголовки запросов.
POST /v1/commandТело запроса:
| Поле | Тип | Обязательное? | Описание |
| devices | dict<string object> | ✔︎ | Устройства, состояние которых нужно изменить. Для каждого устройства передаются ID устройства в системе вендора и новое состояние его функций |
| ID | <string> | ✔︎ | ID устройства в системе вендора |
| states | list<object> | ✔︎ | Список новых состояний (см. Состояние устройства (state)) |
{
"devices": {
"id": {
"states": [
{
"key": string,
"value": {
"type": string,
"type_value": object
}
},
{
// ...
}
]
}
}
}Формат ответа
Вендор отправляет ответ на эндпоинт умного дома Sber. Заголовки см. в разделе Заголовки запросов.
Ответ может быть пустым или включать новые состояния устройств. Например, в случае открытия штор состояние устройства меняется не сразу — тогда лучше сперва вернуть пустой ответ, а затем отправить состояние позднее с помощью метода state.
Пустой ответ:
{
}Ответ с новыми состояниями устройств:
| Поле | Тип | Обязательное? | Описание |
| devices | dict<string object> | ✔︎ | Устройства, состояние которых было изменено. Для каждого устройства передаются ID устройства в системе вендора и новое состояние его функций |
| ID | <string> | ✔︎ | ID устройства в системе вендора |
| states | list<object> | ✔︎ | Список текущих состояний (см. Состояние устройства (state)) |
{
"devices": {
"id": {
"states": [
{
"key": string,
"value": {
"type": string,
"type_value": object
}
},
{
// ...
}
]
}
}
}При возникновении ошибки можно вернуть:
- Список
errors, содержащий объекты error. Каждый объект указывает на конкретные устройства, обновить состояние которых не удалось. - Общую ошибку common error. Описывает проблему в целом и отправляется, только если проблему не удалось соотнести с конкретными устройствами.
Если умный дом уведомил о состоянии нескольких устройств, и состояние части из них вендор смог изменить, а при обновлении остальных произошла ошибка, нужно отправлять ответ с ошибкой error, и передавать в ней список устройств с неизмененными состояниями.
Ошибка конкретного устройства:
{
"errors": [
{
"id": string,
"code": integer,
"message": string
}
]
}Общая ошибка:
{
"code": integer,
"message": string,
"details": list<string>
}Пример запроса и ответа
Умный дом Sber запрашивает изменение состояния розетки.
Запрос:
curl -i -X POST /v1/command \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...{
"devices": {
"ABCD_003": {
"states": [
{
"key": "online",
"value": {
"type": "BOOL",
"bool_value": true
}
},
{
"key": "on_off",
"value": {
"type": "BOOL",
"bool_value": true
}
}
]
}
}
}Успешный ответ:
{
"devices": {
"ABCD_003": {
"states": [
{
"key": "online",
"value": {
"type": "BOOL",
"bool_value": true
}
},
{
"key": "on_off",
"value": {
"type": "BOOL",
"bool_value": true
}
}
]
}
}
}Ответ с ошибкой:
{
"errors": [
{
"id": "ABCD_003",
"code": 500,
"message": "System error"
}
]
}Заметили ошибку?
Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней