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

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

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

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

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

Заголовок

Описание

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

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 из описания команды для управления умением устройства.

Да

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

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

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

Нет

HTTP/1.1 404 Not Found

{
    "request_id": String,
    "status": "error",
    "message": String
}

Параметр

Тип

Описание

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

request_id

String

Идентификатор запроса. Необходимо логировать для расследования инцидентов.

Да

status

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
                    }
                }
            ]
        }
    ]
}'
HTTP/1.1 200 OK

{
   "status": "ok",
   "request_id": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
   "devices": [{
      "id": "lamp-id-1",
      "capabilities": [{
         "type": "devices.capabilities.on_off",
         "state": {
            "instance": "on",
            "action_result": {
               "status": "DONE"
            }
         }
      }]
   }]
}
HTTP/1.1 404 Not Found

{
    "request_id": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
    "status": "error",
    "message": "Устройства не найдены"
}