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

Если пользователь зашел в ПП и хочет поменять состояние устройств, или попросил Алису поменять состояние устройств, платформа умного дома отправит провайдеру текущий запрос.

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

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

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

Получив реплику пользователя (голосовой помощник Алиса) или действие пользователя (ПП), платформа умного дома отправляет запрос на Endpoint URL провайдера (endpoint_url).

POST https://endpoint_url/v1.0/user/devices/action

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

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

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

{
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ]
      }
    ]  
  }
}
payload
Объект с ответом на запрос.
devices *
Массив с устройствами пользователя.
id *
Идентификатор устройства.
capabilities *
Массив с информацией об умениях устройства.
<capability1>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).
<capability2>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).

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

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

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

{
    "request_id": String,
    "capabilities": [
      "<capability1>": Object,
      "<capability2>": Object,
      ...
    ]
}
request_id *
Идентификатор запроса.
capabilities *
Массив с информацией об умениях устройства.
<capability1>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).
<capability2>
Умение и список его параметров. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Список доступных умений (типов умений).

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

Пример

Запрос
curl -i -X POST 'https://endpoint_url/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
                }
            }]
        }]
    }
}
Успешный ответ
{
  "request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3",
  "payload": {
      "devices": [{
          "id": "abc-123",
          "capabilities": [{
              "type": "devices.capabilities.color_setting",
              "state": {
                  "instance": "hsv",
                  "action_result": {
                      "status": "DONE"
                  }
              }
          },
          {
              "type": "devices.capabilities.on_off",
              "state": {
                  "instance": "on",
                  "action_result": {
                      "status": "DONE"
                  }
              }
          }]
     },
     {
        "id": "sock-56GF-3",
        "capabilities": [{
              "type": "devices.capabilities.on_off",
              "state": {
                  "instance": "on",
                  "action_result": {
                      "status": "DONE"
                  }
              }
        }]
     }]
  }
}
Ответ с ошибкой
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",
        "capabilities": [{
              "type": "devices.capabilities.on_off",
              "state": {
                  "instance": "on",
                  "action_result": {
                      "status": "DONE"
                  }
              }
        }]
     }]
  }
}