Запрос состояния устройств (post query)

Умный дом Sber запрашивает у вендора актуальное состояние устройств пользователя. Ответ должен содержать все заявленные функции устройства.

Пример ситуации использования:

  1. Пользователь в приложении вендора изменяет состояние какого-либо устройства. Например, выключает лампочку или меняет ее цвет.
  2. Умный дом периодически запрашивает у вендора состояние устройств пользователя.
  3. Вендор возвращает актуальное состояние устройств, включая текущее состояние лампочки.
  4. Умный дом Sber актуализирует состояние лампочки в приложении Салют, на SberPortal, SberBox и других устройствах с ассистентами Салют.

Формат запроса

Умный дом отправляет запрос на эндпоинт вендора. Заголовки см. в разделе Заголовки запросов.

POST /v1/query

Тело запроса:

Поле Тип Обязательное? Описание
devices list<string> ✔︎ Список идентификаторов устройств, состояние которых нужно вернуть
{
    "devices": [
        "device1_id": string,
        "device2_id": string,
        "device3_id": string
    ]
}

Формат ответа

Вендор отправляет ответ на эндпоинт умного дома. Заголовки см. в разделе Заголовки запросов.

Успешный ответ:

Поле Тип Обязательное? Описание
devices dict<string object> ✔︎ Список устройств пользователя. Для каждого устройства передаются ID устройства в системе вендора и состояние его функций
ID <string> ✔︎ ID устройства в системе вендора
states list<object> ✔︎ Список состояний функций (см. Состояние устройства (state))
{
    "devices": {
        "id": {
            "states": [
                {
                    "key": string,
                    "value": {
                        "type": string,
                        "type_value": object
                    }
                },
                {
                    // ...
                }
            ]
        }
    }
}

При возникновении ошибки нужно возвращать объект типа common error:

{
    "code": integer,
    "message": string,
    "details": list<string>
}

Пример запроса и ответа

Умный дом запрашивает у вендора состояние розетки. Вендор возвращает его.

Запрос:

curl -i -X POST /v1/query \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...
{
    "devices": [
        "ABCD_003"
    ]
}

Успешный ответ:

{
    "devices": {
        "ABCD_003": {
            "states": [
                {
                    "key": "online",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                },
                {
                    "key": "on_off",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                }
            ]
        }
    }
}

Ответ с ошибкой:

{
    "code": 400,
    "message": "Invalid argument",
    "details": []
}

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

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