Запрос изменения состояния устройства (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"
        }
    ]
}

Обновлено 29 апреля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней