Получение полной информации об умном доме пользователя
Запрос на получение полной информации о сущностях умного дома пользователя.
Формат запроса
GET https://api.iot.yandex.net/v1.0/user/info
Заголовки запроса
|
Заголовок |
Описание |
Обязательный |
|
Authorization |
Авторизационный токен oauth-приложения. |
Да |
Формат ответа
Сокращенная структура
HTTP/1.1 200 OK
{
"status": "ok",
"request_id": String,
"rooms": [RoomObject],
"groups": [GroupObject],
"devices": [DeviceObject],
"scenarios": [ScenarioObject],
"households": [HouseholdObject]
}
Полная структура
HTTP/1.1 200 OK
{
"status": "ok",
"request_id": String,
"rooms": [{
"id": String,
"name": String,
"household_id": String,
"devices": [String]
},
{
"id": String,
"name": String,
"household_id": String,
"devices": [String]
}
],
"groups": [{
"id": String,
"name": String,
"aliases": [String],
"household_id": String,
"type": "devices.types.{type}",
"devices": [String],
"capabilities": [{
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {}
},
{
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {}
}
]
}],
"devices": [{
"id": String,
"name": String,
"aliases": [String],
"type": "devices.types.{type}",
"external_id": String,
"skill_id": String,
"household_id": String,
"room": String,
"groups": [String],
"capabilities": [{
"reportable": Boolean,
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {},
"last_updated": Float
},
{
"reportable": Boolean,
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {},
"last_updated": Float
}
],
"properties": []
},
{
"id": String,
"name": String,
"aliases": [String],
"type": "devices.types.{type}",
"external_id": String,
"skill_id": String,
"household_id": String,
"room": String,
"groups": [String],
"capabilities": [{
"reportable": Boolean,
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {},
"last_updated": Float
},
{
"reportable": Boolean,
"retrievable": Boolean,
"type": "devices.capabilities.{capability}",
"parameters": {},
"state": {},
"last_updated": Float
}
],
"properties": []
}
],
"scenarios": [{
"id": String,
"name": String,
"is_active": Boolean
},
{
"id": String,
"name": String,
"is_active": Boolean
}
],
"households": [{
"id": String,
"name": String
}]
}
|
Параметр |
Тип |
Описание |
Обязательный |
|
request_id |
String |
Идентификатор запроса. Необходимо логировать для расследования инцидентов. |
Да |
|
status1 |
String |
Статус обработки запроса. Допустимые значения:
|
Да |
|
rooms |
Array of RoomObjects |
Массив комнат. |
Да |
|
groups |
Array of GroupObjects |
Массив групп устройств. |
Да |
|
devices |
Array of DeviceObjects |
Массив устройств. |
Да |
|
scenarios |
Array of ScenarioObjects |
Массив сценариев. |
Да |
|
households |
Array of HouseholdObjects |
Массив домов. |
Да |
Тип RoomObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
id |
String |
Идентификатор комнаты. |
Да |
|
name |
String |
Название комнаты. |
Да |
|
devices |
Array of Strings |
Массив идентификаторов устройств в комнате. |
Да |
|
household_id |
String |
Идентификатор дома, в котором находится комната. |
Да |
Тип GroupObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
id |
String |
Идентификатор группы устройств. |
Да |
|
name |
String |
Имя группы устройств. |
Да |
|
aliases |
Array of Strings |
Массив с дополнительными именами устройств. |
Да |
|
type |
String |
Тип группы устройств. Совпадает с типом устройств, входящих в группу. |
Да |
|
capabilities |
Array of GroupCapabilityObjects |
Массив с информацией об умениях группы устройств. |
Да |
|
devices |
Array of Strings |
Массив идентификаторов устройств, входящих в группу. |
Да |
|
household_id |
String |
Идентификатор дома группы устройств. |
Да |
Массив capabilities
|
Параметр |
Тип |
Описание |
Обязательный |
|
capability1 |
GroupCapabilityObject |
Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. |
Нет |
|
capability2 |
GroupCapabilityObject |
Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Умения. |
Нет |
Тип GroupCapabilityObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
type |
String |
Да |
|
|
retrievable |
Boolean |
Доступен ли для данного умения запрос состояния. |
Да |
|
parameters |
CapabilityParametersObject |
Параметры умения. Соответствует значению поля |
Да |
|
state |
CapabilityStateObject |
Текущее состояние умения. Если значение |
Да |
Тип DeviceObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
id |
String |
Идентификатор устройства. |
Да |
|
name |
String |
Имя устройства. |
Да |
|
aliases |
Array of Strings |
Массив с дополнительными именами устройства. |
Да |
|
room |
String |
Идентификатор комнаты устройства. Значение |
Да |
|
external_id |
String |
Идентификатор устройства в облаке производителя. |
Да |
|
skill_id |
String |
Идентификатор навыка производителя устройства. |
Да |
|
type |
String |
Да |
|
|
groups |
Array of Strings |
Массив с идентификаторами групп устройства. |
Да |
|
capabilities |
Array of DeviceCapabilityObjects |
Массив с информацией об умениях устройства. |
Да |
|
properties |
Array of DevicePropertyObjects |
Массив с информацией о свойствах устройства. |
Да |
|
household_id |
String |
Идентификатор дома устройства. |
Да |
Массив capabilities
|
Параметр |
Тип |
Описание |
Обязательный |
|
capability1 |
Описание умения. |
Нет |
|
|
capability2 |
Описание умения. |
Нет |
Массив properties
|
Параметр |
Тип |
Описание |
Обязательный |
|
property1 |
Описание свойства. |
Нет |
|
|
property2 |
Описание свойства. |
Нет |
Тип DeviceCapabilityObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
type |
String |
Да |
|
|
reportable |
Boolean |
Оповещает ли умение об изменении состояния платформу умного дома, используя сервис уведомлений. |
Да |
|
retrievable |
Boolean |
Доступен ли для данного умения устройства запрос состояния. |
Да |
|
parameters |
CapabilityParametersObject |
Параметры умения. Соответствует значению поля |
Да |
|
state |
CapabilityStateObject |
Текущее состояние умения. Если значение |
Да |
|
last_updated |
Float |
Время последнего обновления состояния в секундах, формат unix timestamp. |
Да |
Тип DevicePropertyObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
type |
String |
Да |
|
|
reportable |
Boolean |
Оповещает ли свойство об изменении состояния платформу умного дома, используя сервис уведомлений. |
Да |
|
retrievable |
Boolean |
Доступен ли для данного свойства устройства запрос состояния. |
Да |
|
parameters |
PropertyParametersObject |
Параметры свойства. Соответствует значению поля |
Да |
|
state |
PropertyStateObject |
Текущее состояние свойства. Если значение |
Да |
|
last_updated |
Float |
Время последнего обновления состояния в секундах, формат unix timestamp. |
Да |
Тип ScenarioObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
id |
String |
Идентификатор сценария. |
Да |
|
name |
String |
Название сценария. |
Да |
|
is_active |
Boolean |
Флаг того, активен ли этот сценарий сейчас. Неактивный сценарий не удален пользователем, но его нельзя запустить. |
Да |
Тип HouseholdObject
|
Параметр |
Тип |
Описание |
Обязательный |
|
id |
String |
Идентификатор дома. |
Да |
|
name |
String |
Название дома. |
Да |
HTTP/1.1 500 Internal Server Error
{
"request_id": String,
"status": "error",
"message": String
}
|
Параметр |
Тип |
Описание |
Обязательный |
|
request_id |
String |
Идентификатор запроса. Необходимо логировать для расследования инцидентов. |
Да |
|
status |
String |
Статус обработки запроса. Допустимые значения:
|
Да |
|
message |
String |
Сообщение об ошибке. |
Нет |
Пример
curl -i -X GET 'https://api.iot.yandex.net/v1.0/user/info' \
-H 'Authorization: Bearer 123qwe456a...'
HTTP/1.1 200 OK
{
"status": "ok",
"request_id": "8348dba1-ad56-4984-b953-ccd27e42f009",
"rooms": [{
"id": "room-id-1",
"name": "Гостиная",
"household_id": "household-id-1",
"devices": [
"lamp-id-1",
"lamp-id-2",
"lamp-id-3",
"speaker-id-1"
]
},
{
"id": "room-id-2",
"name": "Прихожая",
"household_id": "household-id-1",
"devices": [
"vacuum-cleaner-id-1"
]
}
],
"groups": [{
"id": "light-group-id-1",
"name": "Люстра",
"aliases": ["Верхний свет"],
"household_id": "household-id-1",
"type": "devices.types.light",
"devices": [
"lamp-id-1",
"lamp-id-2",
"lamp-id-3"
],
"capabilities": [{
"retrievable": true,
"type": "devices.capabilities.color_setting",
"parameters": {
"color_model": "hsv",
"temperature_k": {
"min": 1700,
"max": 6500
}
},
"state": {
"instance": "temperature_k",
"value": 3400
}
},
{
"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
}
}
]
}],
"devices": [{
"id": "lamp-id-1",
"name": "Лампочка 1",
"aliases": [],
"type": "devices.types.light",
"external_id": "external-lamp-id-1",
"skill_id": "skill-id-1",
"household_id": "household-id-1",
"room": "room-id-1",
"groups": [
"light-group-id-1"
],
"capabilities": [{
"reportable": false,
"retrievable": true,
"type": "devices.capabilities.on_off",
"parameters": {
"split": false
},
"state": {
"instance": "on",
"value": false
},
"last_updated": 1626681729.2964342
},
{
"reportable": 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
},
"last_updated": 1626681729.2964342
},
{
"reportable": false,
"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": 1626681729.2964342
}
],
"properties": []
},
{
"id": "lamp-id-2",
"name": "Лампочка 2",
"aliases": [],
"type": "devices.types.light",
"external_id": "external-lamp-id-2",
"skill_id": "skill-id-1",
"household_id": "household-id-1",
"room": "room-id-1",
"groups": [
"light-group-id-1"
],
"capabilities": [{
"reportable": false,
"retrievable": true,
"type": "devices.capabilities.on_off",
"parameters": {
"split": false
},
"state": {
"instance": "on",
"value": false
},
"last_updated": 1626681729.2964342
},
{
"reportable": 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
},
"last_updated": 1626681729.2964342
},
{
"reportable": false,
"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": 1626681729.2964342
}
],
"properties": []
},
{
"id": "lamp-id-3",
"name": "Лампочка 3",
"aliases": [],
"type": "devices.types.light",
"external_id": "external-lamp-id-3",
"skill_id": "skill-id-1",
"household_id": "household-id-1",
"room": "room-id-1",
"groups": [
"light-group-id-1"
],
"capabilities": [{
"reportable": false,
"retrievable": true,
"type": "devices.capabilities.on_off",
"parameters": {
"split": false
},
"state": {
"instance": "on",
"value": false
},
"last_updated": 1626681729.2964342
},
{
"reportable": 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
},
"last_updated": 1626681729.2964342
},
{
"reportable": false,
"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": 1626681729.2964342
}
],
"properties": []
},
{
"id": "vacuum-cleaner-id-1",
"name": "Пылесос",
"aliases": [],
"type": "devices.types.vacuum_cleaner",
"external_id": "external-vacuum-cleaner-id-1",
"skill_id": "skill-id-2",
"household_id": "household-id-1",
"room": "room-id-2",
"groups": [],
"capabilities": [{
"reportable": false,
"retrievable": true,
"type": "devices.capabilities.on_off",
"parameters": {
"split": false
},
"state": {
"instance": "on",
"value": false
},
"last_updated": 1626681729.2964342
},
{
"reportable": false,
"retrievable": true,
"type": "devices.capabilities.toggle",
"parameters": {
"instance": "pause"
},
"state": {
"instance": "pause",
"value": false
},
"last_updated": 1626681729.2964342
}
],
"properties": [{
"type": "devices.properties.float",
"reportable": false,
"retrievable": true,
"parameters": {
"instance": "battery_level",
"unit": "unit.percent"
},
"state": {
"instance": "battery_level",
"value": 100
},
"last_updated": 1626681729.2964342
}]
},
{
"id": "speaker-id-1",
"name": "Яндекс Станция",
"aliases": [],
"type": "devices.types.smart_speaker.yandex.station",
"external_id": "external-speaker-id-1",
"skill_id": "Q",
"household_id": "household-id-1",
"room": "room-id-1",
"groups": [],
"capabilities": [],
"properties": []
}
],
"scenarios": [{
"id": "scenario-id-1",
"name": "Световой будильник",
"is_active": true
},
{
"id": "scenario-id-2",
"name": "Время уборки",
"is_active": true
},
{
"id": "scenario-id-3",
"name": "Музыка для настолок",
"is_active": false
}
],
"households": [{
"id": "household-id-1",
"name": "Мой дом"
}]
}
HTTP/1.1 500 Internal Server Error
{
"request_id": "9813e54b-021d-4203-b22a-02c6370d07b1",
"status": "error",
"message": "Внутренняя ошибка сервера"
}
Число с плавающей точкой с точностью до 6-9 десятичных знаков.
Cтрока, выделяется кавычками, например "Hello world".
Логическое значение без кавычек: true (истина) или false (ложь).
Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true, false, объект или массив. Массив выделяется квадратными скобками []:
"cities": ["Moscow", "Tokyo", "New York"]
Тип
Array of Strings
Описание
Массив идентификаторов устройств в комнате.
Обязательный
Да
Тип
String
Описание
Идентификатор группы устройств.
Обязательный
Да
Тип
String
Описание
Имя группы устройств.
Обязательный
Да
Тип
Array of Strings
Описание
Массив идентификаторов устройств, входящих в группу.
Обязательный
Да
Тип
String
Описание
Обязательный
Да
Тип
String
Описание
Идентификатор устройства.
Обязательный
Да
Тип
String
Описание
Имя устройства.
Обязательный
Да
Тип
Array of Strings
Описание
Массив с дополнительными именами устройства.
Обязательный
Да
Тип
String
Описание
Обязательный
Да
Тип
String
Описание
Идентификатор комнаты устройства. Значение null передается, если устройство не привязано к комнате.
Обязательный
Да
Тип
Array of Strings
Описание
Массив с идентификаторами групп устройства.
Обязательный
Да
Тип
String
Описание
Идентификатор сценария.
Обязательный
Да
Тип
String
Описание
Название сценария.
Обязательный
Да
Тип
String
Описание
Идентификатор дома.
Обязательный
Да
Тип
String
Описание
Название дома.
Обязательный
Да
Тип
String
Описание
Идентификатор запроса. Необходимо логировать для расследования инцидентов.
Обязательный
Да
Тип
String
Описание
Статус обработки запроса. Допустимые значения:
error.
Обязательный
Да
Тип
String
Описание
Сообщение об ошибке.
Обязательный
Нет