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

Изменяет текущее состояние устройств пользователя.

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

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

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

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

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

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

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

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

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

{
  "payload": {
    "devices":[
      {
        "id": String,
        "custom_data": Object,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ]
      }
    ]  
  }
}
Параметр Тип Описание Обязательный
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Должен быть уникален среди всех устройств производителя. Да
custom_data Object Объект, который провайдер прислал вместе с устройством в ответ на запрос Информация об устройствах пользователя. Состоит из набора пар "ключ":"значение" любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. Нет
capabilities Array of objects Массив с информацией об умениях устройства. Да
Объект capabilities
<capability1> Object Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Да
<capability2> Object Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Да
Параметр Тип Описание Обязательный
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Должен быть уникален среди всех устройств производителя. Да
custom_data Object Объект, который провайдер прислал вместе с устройством в ответ на запрос Информация об устройствах пользователя. Состоит из набора пар "ключ":"значение" любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. Нет
capabilities Array of objects Массив с информацией об умениях устройства. Да
Объект capabilities
<capability1> Object Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Да
<capability2> Object Умение и команда на его изменение. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Да

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

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

HTTP/1.1 200 OK

{
    "request_id": String,
    "payload": {
      "devices": [
        {
          "id": String,
          "capabilities": [
            "<capability1>": Object,
            "<capability2>": Object,
            ...
          ],
          "action_result": {
            "status": String,
            "error_code": String,
            "error_message": String
          }
        },
        ...
      ]
    }
}
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Да
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Должен быть уникален среди всех устройств производителя. Да
capabilities Array of objects Массив с информацией об умениях устройства. Да, если отсутствует action_result
action_result Object

Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует capabilities.

Примечание.

Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства.

Ответ на запрос считается успешным (status:"DONE"), если хотя бы одно состояние у устройства изменилось.

 Да, если отсутствует capabilities
Объект capabilities
<capability1> Object Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Нет
<capability2> Object Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Нет
Объект action_result
status String

Статус изменения состояния у устройства. Допустимые значения:

  • DONE — состояние устройства успешно изменено;
  • ERROR — при изменении состояния у устройства произошла ошибка.
 Нет
error_code String Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование . Нет
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Да
payload Object Объект с устройствами. Да
Объект payload
devices Array of objects Массив с устройствами пользователя. Да
Объект devices
id String Идентификатор устройства. Должен быть уникален среди всех устройств производителя. Да
capabilities Array of objects Массив с информацией об умениях устройства. Да, если отсутствует action_result
action_result Object

Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует capabilities.

Примечание.

Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства.

Ответ на запрос считается успешным (status:"DONE"), если хотя бы одно состояние у устройства изменилось.

 Да, если отсутствует capabilities
Объект capabilities
<capability1> Object Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Нет
<capability2> Object Результат выполнения команды. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Нет
Объект action_result
status String

Статус изменения состояния у устройства. Допустимые значения:

  • DONE — состояние устройства успешно изменено;
  • ERROR — при изменении состояния у устройства произошла ошибка.
 Нет
error_code String Код возможной ошибки из списка. Если поле непустое, параметры capabilities и properties будут проигнорированы. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование . Нет

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

Пример

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

Тело запроса

{
    "payload": {
        "devices": [{
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            },
            "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": false
                }
            }]
        }, {
            "id": "sock-56GF-3",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": false
                }
            }]
        }]
    }
}