Информация о состояниях устройств пользователя

Протокол работы с платформой

API платформы умного дома

REST

Запрашивает информацию о текущем состоянии устройств пользователя.

Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение Дом с Алисой и хочет поменять состояние устройств.

В ответ на такой запрос провайдеру необходимо вернуть состояния запрошенных устройств пользователя.

Примечание.

Умения, для которых запрос состояния недоступен (имеющие атрибут retrievable=false), можно не включать в ответ, так как их состояние будет проигнорировано.

Формат запроса платформы умного дома

Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).

POST https://example.com/v1.0/user/devices/query

Заголовки запроса


Заголовок	Описание	Обязательный
`Authorization`	Авторизационный токен пользователя.	Да
`Content-Type`	Формат передаваемых/отправляемых данных. Возможные значения: application/json.	Да, в операциях с http-методом POST
`X-Request-Id`	Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем.	Да


Заголовок	Описание	Обязательный
`Authorization`	Авторизационный токен пользователя.	Да
`Content-Type`	Формат передаваемых/отправляемых данных. Возможные значения: application/json.	Да, в операциях с http-методом POST
`X-Request-Id`	Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем.	Да

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

{
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
}


Параметр	Тип	Описание	Обязательный
`devices`	Array of objects	Массив с устройствами пользователя.	Да
Объект `devices`
`id`	String	Идентификатор устройства. Должен быть уникален среди всех устройств производителя.	Да
`custom_data`	Object	Объект, который был передан провайдером для устройства в ответе на запрос Информация об устройствах пользователя.	Нет


Параметр	Тип	Описание	Обязательный
`devices`	Array of objects	Массив с устройствами пользователя.	Да
Объект `devices`
`id`	String	Идентификатор устройства. Должен быть уникален среди всех устройств производителя.	Да
`custom_data`	Object	Объект, который был передан провайдером для устройства в ответе на запрос Информация об устройствах пользователя.	Нет

Формат ответа провайдера

Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.

HTTP/1.1 200 OK

{
  "request_id": String,
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ],
        "properties": [
          "<property1>": Object,
          "<property2>": Object,
          ...
        ],
        "error_code": String,
        "error_message": String
      },
      ...
    ]  
  }
}


Параметр	Тип	Описание	Обязательный
`request_id`	String	Идентификатор запроса.	Да
`payload`	Object	Объект с устройствами.	Да
Объект `payload`
`devices`	Array of objects	Массив с устройствами пользователя.	Да
Объект `devices`
`id`	String	Идентификатор устройства. Должен быть уникален среди всех устройств производителя.	Да
`capabilities`	Array of objects	Массив с информацией об умениях устройства.	Нет
`properties`	Array of objects	Массив с информацией о свойствах устройства.	Нет
`error_code`	String	Код возможной ошибки из списка. Если поле непустое, параметры `capabilities` и `properties` будут проигнорированы.	Нет
`error_message`	String	Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование .	Нет
Объект `capabilities`
`<capability1>`	Object	Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях.	Нет
`<capability2>`	Object	Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях.	Нет
Объект `properties`
`<property1>`	Object	Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах.	Нет
`<property2>`	Object	Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах.	Нет


Параметр	Тип	Описание	Обязательный
`request_id`	String	Идентификатор запроса.	Да
`payload`	Object	Объект с устройствами.	Да
Объект `payload`
`devices`	Array of objects	Массив с устройствами пользователя.	Да
Объект `devices`
`id`	String	Идентификатор устройства. Должен быть уникален среди всех устройств производителя.	Да
`capabilities`	Array of objects	Массив с информацией об умениях устройства.	Нет
`properties`	Array of objects	Массив с информацией о свойствах устройства.	Нет
`error_code`	String	Код возможной ошибки из списка. Если поле непустое, параметры `capabilities` и `properties` будут проигнорированы.	Нет
`error_message`	String	Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование .	Нет
Объект `capabilities`
`<capability1>`	Object	Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях.	Нет
`<capability2>`	Object	Умение и его статус. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях.	Нет
Объект `properties`
`<property1>`	Object	Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах.	Нет
`<property2>`	Object	Свойство и его статус. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах.	Нет

Коды, связанные с запросом

HTTP/1.1 404 Not Found

Глобальные коды

Пример

В примере описаны свойства светильника с регулировкой цвета и розетки.

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Тело запроса

{
    "devices": [
        {
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            } 
        },
        {
            "id": "sock-56GF-3" 
        }   
    ]
}

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [{
            "id": "abc-123",
            "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": true
                }
            }]
        },
        {
            "id": "abc-123",
            "error_code": "DEVICE_NOT_FOUND",
            "error_message": "the human readable error message"
        }, 
        {
            "id": "sock-56GF-3",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        }]
    }
}

HTTP/1.1 404 Not Found

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

Информация об устройствах пользователя

Изменение состояния у устройств

В этой статье

Формат запроса платформы умного дома Формат ответа провайдера Пример

Информация об устройствах пользователя

Изменение состояния у устройств