Управление умениями группы устройств
Отправляет действия на группу устройств.
Формат запроса
POST https://api.iot.yandex.net/v1.0/groups/{group_id}/actions
group_id |
Идентификатор группы устройств пользователя |
Заголовки запроса
Заголовок |
Описание |
Обязательный |
Authorization |
Авторизационный токен oauth-приложения. |
Да |
Формат тела запроса
{
"actions": [
{
"type": "devices.capabilities.{capability}",
"state": {}
}
]
}
Параметр |
Тип |
Описание |
Обязательный |
actions |
Array of objects |
Массив действий для группы устройств. |
Да |
Массив actions
Параметр |
Тип |
Описание |
Обязательный |
capability1 |
CapabilityObject |
Умение и команда на его изменение. |
Нет |
capability2 |
CapabilityObject |
Умение и команда на его изменение. |
Нет |
Тип CapabilityObject
Параметр |
Тип |
Описание |
Обязательный |
type |
String |
Да |
|
state |
CapabilityStateObject |
Целевое состояние умения. Соответствует значению поля |
Да |
Формат ответа
Примечание
Так как устройства в группе могут по-разному отреагировать на присланное действие, в ответе возвращается результат выполнения действия на каждом устройстве в группе.
HTTP/1.1 200 OK
{
"status": "ok",
"request_id": String,
"devices": [{
"id": String,
"capabilities": [{
"type": String,
"state": {
"instance": String,
"action_result": {
"status": String
}
}
}]
},
{
"id": String,
"capabilities": [{
"type": String,
"state": {
"instance": String,
"action_result": {
"status": String
}
}
}]
}
]
}
Параметр |
Тип |
Описание |
Обязательный |
request_id |
String |
Идентификатор запроса. Необходимо логировать для расследования инцидентов. |
Да |
status |
String |
Статус обработки запроса. Допустимые значения:
|
Да |
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 |
Статус изменения состояния у устройства. Допустимые значения:
|
Да |
error_code |
String |
Код ошибки из списка возможных ошибок. |
Нет |
error_message |
String |
Расширенное человекочитаемое описание возможной ошибки. |
Нет |
HTTP/1.1 404 Not Found
{
"request_id": String,
"status": "error",
"message": String
}
Параметр |
Тип |
Описание |
Обязательный |
request_id |
String |
Идентификатор запроса. Необходимо логировать для расследования инцидентов. |
Да |
status |
String |
Статус обработки запроса. Допустимые значения:
|
Да |
message |
String |
Сообщение об ошибке. |
Нет |
Пример
ЗапросУспешный ответОтвет с ошибкой
curl --request POST 'https://api.iot.yandex.net/v1.0/groups/light-group-id-1/actions' \ --header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "actions": [ { "type": "devices.capabilities.on_off", "state": { "instance": "on", "value": true } } ] }'
HTTP/1.1 200 OK { "status": "ok", "request_id": "35e9d24a-40f3-409d-b654-2cf4d87fe593", "devices": [{ "id": "lamp-id-1", "capabilities": [{ "type": "devices.capabilities.on_off", "state": { "instance": "on", "action_result": { "status": "DONE" } } }] }, { "id": "lamp-id-2", "capabilities": [{ "type": "devices.capabilities.on_off", "state": { "instance": "on", "action_result": { "status": "DONE" } } }] }, { "id": "lamp-id-3", "capabilities": [{ "type": "devices.capabilities.on_off", "state": { "instance": "on", "action_result": { "status": "DONE" } } }] } ] }
HTTP/1.1 404 Not Found { "request_id": "667b3e0f-47a8-4136-9211-b4ff59062315", "status": "error", "message": "Группа устройств не найдена" }
Список пар "ключ": значение
, разделенных запятой. Выделяется фигурными скобками {}
.
{
"name": "John",
"surname": "Smith"
}
Cтрока, выделяется кавычками, например "Hello world"
.
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true
, false
, объект или массив. Массив выделяется квадратными скобками []
:
"cities": ["Moscow", "Tokyo", "New York"]
Идентификатор группы устройств пользователя
Тип
String
Описание
Обязательный
Да
Тип
StateResultObject
Описание
Состояние умения.
Обязательный
Да
Тип
String
Описание
Статус изменения состояния у устройства. Допустимые значения:
DONE
— состояние устройства успешно изменено;ERROR
— при изменении состояния у устройства произошла ошибка.
Обязательный
Да
Тип
Описание
Идентификатор запроса. Необходимо логировать для расследования инцидентов.
Обязательный
Да
Тип
String
Описание
Статус обработки запроса. Допустимые значения:
error
.
Обязательный
Да
Тип
String
Описание
Сообщение об ошибке.
Обязательный
Нет