Управление умениями устройств

Отправляет действия на устройства пользователя.

  1. Формат запроса
  2. Формат ответа
  3. Пример

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

POST https://api.iot.yandex.net/v1.0/devices/actions

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

Заголовок Описание Обязательный
Authorization Авторизационный токен oauth-приложения. Да
Заголовок Описание Обязательный
Authorization Авторизационный токен oauth-приложения. Да

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

{
	"devices": [{
		"id": String,
		"actions": [{
			"type": "devices.capabilities.{capability}",
			"state": {}
		}]
	}]
}
Параметр Тип Описание Обязательный
devices Array of DeviceActionsObjects Массив действий для устройств. Да
Массив devices
deviceActions1 DeviceActionObject Набор действий для устройств. Нет
deviceActions2 DeviceActionObject Набор действий для устройств. Нет
Тип DeviceActionsObject
id String Идентификатор устройства Да
actions Array of CapabilityObjects Массив действий для устройства. Да
Массив actions
capability1 CapabilityObject Умение и команда на его изменение. Нет
capability2 CapabilityObject Умение и команда на его изменение. Нет
Тип CapabilityObject
type String Тип умения. Да
state CapabilityStateObject Целевое состояние умения. Соответствует значению поля state из описания команды для управления умением устройства. Да
Параметр Тип Описание Обязательный
devices Array of DeviceActionsObjects Массив действий для устройств. Да
Массив devices
deviceActions1 DeviceActionObject Набор действий для устройств. Нет
deviceActions2 DeviceActionObject Набор действий для устройств. Нет
Тип DeviceActionsObject
id String Идентификатор устройства Да
actions Array of CapabilityObjects Массив действий для устройства. Да
Массив actions
capability1 CapabilityObject Умение и команда на его изменение. Нет
capability2 CapabilityObject Умение и команда на его изменение. Нет
Тип CapabilityObject
type String Тип умения. Да
state CapabilityStateObject Целевое состояние умения. Соответствует значению поля state из описания команды для управления умением устройства. Да

Формат ответа

HTTP/1.1 200 OK

{
   "status": "ok",
   "request_id": String,
   "devices": [{
      "id": String,
      "capabilities": [{
         "type": "devices.capabilities.{capability}",
         "state": {
            "instance": String,
            "action_result": {
               "status": String;
            }
         }
      }]
   }]
}
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Необходимо логировать для расследования инцидентов. Да
status String Статус обработки запроса. Допустимые значения:
  • ok.
 Да
devices Array of DeviceActionsResultObjects Результаты выполнения действий на устройствах. Да
Массив devices
deviceActionsResult1 DeviceActionResultObject Результат выполнения действий на устройстве. Нет
deviceActionsResult2 DeviceActionResultObject Результат выполнения действий на устройстве. Нет
Тип DeviceActionsResultObject
id String Идентификатор устройства Да
capabilities CapabilityActionResultObject Результаты действий. Да
Тип CapabilityActionResultObject
type String Тип умения. Да
state StateResultObject Состояние умения. Да
Тип StateResultObject
instance String Функция умения. Да
action_result ActionResultObject Результат действия. Да
Тип ActionResultObject
status String Статус изменения состояния у устройства. Допустимые значения:
  • DONE — состояние устройства успешно изменено;
  • ERROR — при изменении состояния у устройства произошла ошибка.
 Да
error_code String Код ошибки из списка возможных ошибок. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Нет
Параметр Тип Описание Обязательный
request_id String Идентификатор запроса. Необходимо логировать для расследования инцидентов. Да
status String Статус обработки запроса. Допустимые значения:
  • ok.
 Да
devices Array of DeviceActionsResultObjects Результаты выполнения действий на устройствах. Да
Массив devices
deviceActionsResult1 DeviceActionResultObject Результат выполнения действий на устройстве. Нет
deviceActionsResult2 DeviceActionResultObject Результат выполнения действий на устройстве. Нет
Тип DeviceActionsResultObject
id String Идентификатор устройства Да
capabilities CapabilityActionResultObject Результаты действий. Да
Тип CapabilityActionResultObject
type String Тип умения. Да
state StateResultObject Состояние умения. Да
Тип StateResultObject
instance String Функция умения. Да
action_result ActionResultObject Результат действия. Да
Тип ActionResultObject
status String Статус изменения состояния у устройства. Допустимые значения:
  • DONE — состояние устройства успешно изменено;
  • ERROR — при изменении состояния у устройства произошла ошибка.
 Да
error_code String Код ошибки из списка возможных ошибок. Нет
error_message String Расширенное человекочитаемое описание возможной ошибки. Нет

Пример

curl --request POST 'https://api.iot.yandex.net/v1.0/devices/actions' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "devices": [
        {
            "id": "lamp-id-1",
            "actions": [
                {
                    "type": "devices.capabilities.on_off",
                    "state": {
                        "instance": "on",
                        "value": true
                    }
                }
            ]
        }
    ]
}'