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

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

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

GET https://api.iot.yandex.net/v1.0/devices/{device_id}

device_id

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

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

Заголовок

Описание

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

Authorization

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

Да

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

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": String,
	"id": String,
	"name": String,
	"aliases": [String],
	"type": "devices.types.{type}",
	"state": String,
	"groups": [String],
	"room": String,
	"external_id": String,
	"skill_id": String,
	"capabilities": [{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {},
			"last_updated": Float
		},
		{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {},
			"last_updated": Float
		}
	],
	"properties": [{
			"retrievable": Boolean,
			"type": "devices.properties.{property}",
			"parameters": {},
			"state": {},
			"last_updated": Float
        },
        {
			"retrievable": Boolean,
			"type": "devices.properties.{property}",
			"parameters": {},
			"state": {},
			"last_updated": Float
        }
    ]
}

Параметр

Тип

Описание

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

status

String

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

  • ok.

Да

request_id

String

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

Да

id

String

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

Да

name

String

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

Да

aliases

Array of Strings

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

Да

room

String

Идентификатор комнаты устройства. Значение null передается, если устройство не привязано к комнате.

Да

external_id

String

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

Да

skill_id

String

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

Да

type

String

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

Да

state

String

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

  • online;
  • offline.

Да

groups

Array of Strings

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

Да

capabilities

Array of CapabilityObjects

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

Да

properties

Array of PropertyObjects

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

Да

Массив capabilities

Параметр

Тип

Описание

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

capability1

CapabilityObject

Описание умения.

Нет

capability2

CapabilityObject

Описание умения.

Нет

Массив properties

Параметр

Тип

Описание

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

property1

PropertyObject

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

Нет

property2

PropertyObject

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

Нет
Тип CapabilityObject

Параметр

Тип

Описание

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

type

String

Тип умения.

Да

retrievable

Boolean

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

Да

parameters

CapabilityParametersObject

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

Да

state

CapabilityStateObject

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

Да

last_updated

Float

Время последнего обновления состояния в секундах, формат unix timestamp.

Да
Тип PropertyObject

Параметр

Тип

Описание

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

type

String

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

Да

retrievable

Boolean

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

Да

parameters

PropertyParametersObject

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

Да

state

PropertyStateObject

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

Да

last_updated

Float

Время последнего обновления состояния в секундах, формат unix timestamp.

Да

 
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/devices/lamp-id-1' \
-H 'Authorization: Bearer 123qwe456a...'

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": "fd9299b8-f927-44f1-8728-8a0b35f1c72a",
	"id": "lamp-id-1",
	"name": "Лампочка 1",
	"aliases": [],
	"type": "devices.types.light",
	"state": "online",
	"groups": [
		"light-group-id-1"
	],
	"room": "room-id-1",
	"external_id": "external-lamp-id-1",
	"skill_id": "skill-id-1",
	"capabilities": [{
			"retrievable": true,
			"type": "devices.capabilities.on_off",
			"parameters": {
				"split": false
			},
			"state": {
				"instance": "on",
				"value": false
			},
			"last_updated": 1626702522.614036
		},
		{
			"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
			},
			"last_updated": 1626702522.614036
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.color_setting",
			"parameters": {
				"color_model": "rgb",
				"temperature_k": {
					"min": 1700,
					"max": 6500
				}
			},
			"state": {
				"instance": "temperature_k",
				"value": 3400
			},
			"last_updated": 1626702522.614036
		}
	],
	"properties": []
}

HTTP/1.1 404 Not Found

{
    "request_id": "9813e54b-021d-4203-b22a-02c6370d07b1",
    "status": "error",
    "message": "Устройство не найдено"
}

Предыдущая
Получение полной информации об умном доме пользователя
Следующая
Управление умениями устройств