Получение состояния устройств (get state)

Обновлено 30 мая 2024

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

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

1. Вендор периодически запрашивает у умного дома Sber состояние устройств пользователя — это нужно, чтобы показывать актуальную информацию в приложении вендора.
2. Умный дом возвращает состояние устройств пользователя.
3. Вендор обновляет свою базу данных и показывает актуальную информацию в своем приложении.

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

Вендор отправляет запрос на эндпоинт умного дома Sber: https://partners.iot.sberdevices.ru/. Обратите внимание, что для обращения к облаку Sber на сервере вендора должны быть установлены российские сертификаты.

Заголовки см. в разделе Заголовки запросов.

GET /v1/state?user_id=<string>&device_ids=<device_ids>

Параметры запроса:

Поле	Тип	Обязательное?	Описание
user_id	string	✔︎	Идентификатор пользователя в системе вендора. Умный дом получает ID при связывании аккаунтов и затем хранит их (см. метод Запрос информации о пользователе (get user))
device_ids	list<string>		Список идентификаторов устройств в системе вендора, состояние которых нужно вернуть. Если не указать, вернется состояние всех устройств пользователя

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

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

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

Поле	Тип	Обязательное?	Описание
devices	list<object>	✔︎	Список состояний устройств (см. Состояние устройства (state))

{
    "devices": {
        "id1": {
            "states": [
                {
                    "key": string,
                    "value": {
                        "type": string,
                        "type_value": object
                    }
                },
                {
                    // ...
                }
            ]
        }
    }
}

При возникновении ошибки возвращается объект типа common error:

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

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

Обновлено 30 мая 2024

Вендор запрашивает состояние розетки пользователя. У розетки есть функции online и on_off, умный дом возвращает их состояние.

Запрос:

curl -i -X GET /v1/state?user_id=AB12345&device_ids=ABCD_003 HTTP/1.1 \
-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
                    }
                }
            ]
        }
    }
}

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

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