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

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

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

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

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

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

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

POST https://functions.yandexcloud.net/<function_id>?integration=raw

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

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

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

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

Подробнее о том, как отдавать коды состояния, отличные от 200 OK, читайте в документации.

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 POST https://functions.yandexcloud.net/<function_id>?integration=raw \
-H 'Content-Type: application/json' \
-d '{
      "headers": {
        "request_id": "1111-aaaa-2222-bbbb",
        "authorization": "Bearer 123qwe456a..."
      },
      "request_type": "action",
      "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
            }
          }]
        }]
      },
      "api_version": 1.0
    }'

Часто задаваемые вопросы

Можно ли настроить оповещения об изменениях в состоянии устройств?

Для таких оповещений необходим асинхронный протокол. Он не используется в Диалогах.