Получение информации о состоянии группы устройств

Запрос информации об актуальном состоянии группы устройств пользователя.

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

GET https://api.iot.yandex.net/v1.0/groups/{group_id}

group_id

Идентификатор группы устройств пользователя.

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

Заголовок

Описание

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

Authorization

Авторизационный токен oauth-приложения.

Да

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

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": String,
	"id": String,
	"name": String,
	"aliases": [String],
	"type": "devices.types.{type}",
	"state": "online",
	"capabilities": [{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {}
		},
		{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {}
		}
	],
	"devices": [{
			"id": String,
			"name": String,
			"type": "devices.types.{type}"
		},
		{
			"id": String,
			"name": String,
			"type": "devices.types.{type}"
		}
	]
}

Параметр

Тип

Описание

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

status

String

Статус обработки запроса. Допустимые значения:

  • ok.

Да

request_id

String

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

Да

id

String

Идентификатор группы устройств.

Да

name

String

Имя группы устройств.

Да

aliases

Array of Strings

Массив с дополнительными именами устройств.

Да

type

String

Тип группы устройств. Совпадает с типом устройств, входящих в группу.

Да

state

String

Состояние группы устройств. Допустимые значения:

  • online;
  • offline;
  • split — устройства в группе находятся в разных состояниях.

Да

capabilities

Array of CapabilityObjects

Массив с информацией об умениях группы устройств.

Да

devices

Array of GroupDeviceInfoObjects

Массив с информацией об устройствах в группе.

Да

Массив capabilities

Параметр

Тип

Описание

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

capability1

CapabilityObject

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

Нет

capability2

CapabilityObject

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

Нет

Тип CapabilityObject

Параметр

Тип

Описание

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

type

String

Тип умения.

Да

retrievable

Boolean

Доступен ли для данного умения запрос состояния

Да

parameters

CapabilityParametersObject

Параметры умения. Соответствует значению поля parameters из описания умения.

Да

state

CapabilityStateObject

Текущее состояние умения. Если значение null, значит это умение не находится в одинаковом состоянии на устройствах в группе. Соответствует значению поля state из описания умения.

Да

Массив devices

Параметр

Тип

Описание

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

device1

GroupDeviceInfoObject

Описание устройства в группе.

Нет

device2

GroupDeviceInfoObject

Описание устройства в группе.

Нет

Тип GroupDeviceInfoObject

Параметр

Тип

Описание

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

id

String

Идентификатор устройства.

Да

name

String

Имя устройства.

Да

type

String

Тип устройства.

Да

 
HTTP/1.1 404 Not Found

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

Параметр

Тип

Описание

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

request_id

String

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

Да

status

String

Статус обработки запроса. Допустимые значения:

  • error.

Да

message

String

Сообщение об ошибке.

Нет

Коды ошибок

Пример

curl -i -X GET 'https://api.iot.yandex.net/v1.0/groups/lamp-group-id-1' \
-H 'Authorization: Bearer 123qwe456a...'

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": "4ea5619b-c4c5-41af-930b-4b317f7bdad6",
	"id": "light-group-id-1",
	"name": "Люстра",
	"aliases": ["Верхний свет"],
	"type": "devices.types.light",
	"state": "online",
	"capabilities": [{
			"retrievable": true,
			"type": "devices.capabilities.on_off",
			"parameters": {
				"split": false
			},
			"state": {
				"instance": "on",
				"value": false
			}
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.range",
			"parameters": {
				"instance": "brightness",
				"unit": "unit.percent",
				"random_access": true,
				"range": {
					"min": 1,
					"max": 100,
					"precision": 1
				}
			},
			"state": {
				"instance": "brightness",
				"value": 100
			}
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.color_setting",
			"parameters": {
				"color_model": "hsv",
				"temperature_k": {
					"min": 1700,
					"max": 6500
				}
			},
			"state": {
				"instance": "temperature_k",
				"value": 3400
			}
		}
	],
	"devices": [{
			"id": "lamp-id-1",
			"name": "Лампочка 1",
			"type": "devices.types.light"
		},
		{
			"id": "lamp-id-2",
			"name": "Лампочка 2",
			"type": "devices.types.light"
		},
		{
			"id": "lamp-id-3",
			"name": "Лампочка 3",
			"type": "devices.types.light"
		}
	]
}

HTTP/1.1 404 Not Found

{
    "request_id": "667b3e0f-47a8-4136-9211-b4ff59062315",
    "status": "error",
    "message": "Группа устройств не найдена"
}

Предыдущая
Управление умениями устройств
Следующая
Управление умениями группы устройств