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

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

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

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

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

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

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

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

Заголовок

Описание

Обязательный

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

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

Да

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

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

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

Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке Тестирование.

Нет

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

HTTP/1.1 404 Not Found

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

Пример

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
                }
            }]
        }]
    }
}

HTTP/1.1 200 OK

{
  "request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3",
  "payload": {
      "devices": [{
          "id": "abc-123",
          "capabilities": [{
              "type": "devices.capabilities.color_setting",
              "state": {
                  "instance": "hsv",
                  "action_result": {
                      "status": "ERROR",
                      "error_code": "INVALID_ACTION",
                      "error_message": "the human readable error message"
                  }
              }
          },
          {
              "type": "devices.capabilities.on_off",
              "state": {
                  "instance": "on",
                  "action_result": {
                      "status": "DONE"
                  }
              }
          }]
     },
     {
        "id": "sock-56GF-3",
        "action_result": {
          "status": "ERROR",
          "error_code": "DEVICE_UNREACHABLE"
        }
     }]
  }
}

HTTP/1.1 404 Not Found

Предыдущая
Информация о состояниях устройств пользователя
Следующая
Оповещение о разъединении аккаунтов