--- metadata: - name: generator content: Diplodoc Platform v5.66.0 alternate: - https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/get-devices.md - https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md - href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md type: text/markdown title: Markdown version - href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/llms.txt?revision=r21995741 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/ru/llms.txt?revision=r21995741 # Информация об устройствах пользователя Запрашивает информацию о поддерживаемых устройствах пользователя. Платформа умного дома отправит провайдеру текущий запрос при выполнении условий: - Аккаунты на Яндексе и на стороне провайдера [связаны](https://yandex.ru/dev/dialogs/smart-home/doc/ru/auth/when-to-use.md). - Пользователь зашел в приложение [![](../_images/smart-home-app.svg) Дом с Алисой](https://alice.yandex.ru/smart-home) → ![Плюс](../_images/plus.svg) → **Устройство умного дома** и напротив названия производителя нажал кнопку **Обновить**. {% note info %} После связки аккаунтов на Яндексе и на стороне провайдера также отправляется данный запрос. {% endnote %} В ответ на такой запрос провайдеру необходимо вернуть список всех поддерживаемых устройств пользователя с описанием доступных [умений](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md) и [свойств](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). Максимальное количество устройств пользователя — 301. Если часть устройств недоступна и провайдер не смог отправить информацию о них, платформа умного дома оставит эти устройства пользователя без изменений. Удалить устройство из списка может только сам пользователь. ## Формат запроса платформы умного дома {#input} Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com). ```bash translate=no GET https://example.com/v1.0/user/devices ``` #### Заголовки запроса {#headers} #| || **Заголовок** | **Описание** | **Обязательный** || || Authorization | Авторизационный токен пользователя. | Да || || X-Request-Id | Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. | Да || |# ## Формат ответа провайдера {#output-structure} Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату. {% list tabs %} - Успешный ответ ```json translate=no { "request_id": String, "payload": { "user_id": String, "devices": [ { "id": String, "name": String, "status_info": { "reportable": Boolean }, "description": String, "room": String, "type": String, "custom_data": Object, "capabilities": [ "": Object, "": Object, ... ], "properties": [ "": Object, "": Object, ... ], "device_info": { "manufacturer": String, "model": String, "hw_version": String, "sw_version": String } }, ... ] } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || request_id | [String](*string) | Идентификатор запроса. | Да || || payload | [Object](*object) | Объект с устройствами. | Да || |#
**Объект `payload`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || user_id | [String](*string) | Идентификатор пользователя. | Да || || devices | [Array](*array) of [objects](*object) | Массив с устройствами пользователя. | Да || |#
**Объект `devices`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || id | [String](*string) | Идентификатор устройства. Должен быть уникален среди всех устройств производителя. | Да || || name | [String](*string) | Название устройства. | Да || || status_info | [Object](*object) | Информация о состоянии устройства. | Да || || description | [String](*string) | Описание устройства. | Нет || || room | [String](*string) | Название помещения, в котором расположено устройство. | Нет || || type | [String](*string) | Тип устройства. Со списком типов устройств можно ознакомиться в разделе [Типы устройств](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/device-types.md). | Да || || custom_data | [Object](*object) | Объект, который состоит из набора пар `"ключ":"значение"` любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. Платформа умного дома сохранит этот объект и будет отправлять его в запросах [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md), [Изменение состояния у устройств](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-action.md). | Нет || || capabilities | [Array](*array) of [objects](*object) | Массив с информацией об [умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md) устройства. | Да, если отсутствует `properties` || || properties | [Array](*array) of [objects](*object) | Массив с информацией о [свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md) устройства. | Да, если отсутствует `capabilities` || || device_info | [Object](*object) | Дополнительная техническая информация об устройстве. Чтобы посмотреть эту информацию, на главном экране приложения [![](../_images/smart-home-app.svg) Дом с Алисой](https://alice.yandex.ru/smart-home) выберите устройство, в правом верхнем углу нажмите ![Изображение шестеренки](../_images/settings.svg) и выберите **Об устройстве**. Данная информация поможет быстрее идентифицировать устройство при обращении пользователя в поддержку Яндекса или к производителю. | Да, для [официальных навыков](https://yandex.ru/dev/dialogs/smart-home/doc/ru/certification.md) || |#
**Объект `status_info`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || reportable | [Boolean](*boolean) | Параметр показывает, умеет ли устройство передавать свой статус [status](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md#structure-in) («в сети» или «не в сети»). Допустимые значения: - `true` — устройство обязано отправлять уведомления `online`/`offline` через [`/callback/state`](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md). В приложении ![](../_images/smart-home-app.svg)[Дом с Алисой](https://alice.yandex.ru/smart-home) для устройства включается бейдж «Не в сети» и пуш-уведомления о потере связи. У устройства в приложении появляется настройка **Уведомления о состоянии** → **Не в сети** → **Уведомить о состоянии устройства «не в сети»**. - `false` — допустим **только если устройство физически не поддерживает отслеживание доступности**. Нереализованность на стороне провайдера («не успели», «планируем позже», «в облаке это дорого») основанием не является. {% note alert %} `reportable: true` при фактически не отправляемых уведомлениях `online`/`offline` — основание для отклонения навыка на модерации. {% endnote %} Подробнее о требованиях к отправке уведомлений см. в разделе [Требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md). | Да || |#
**Объект `capabilities`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || \ | [Object](*object) | Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе [Об умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md). | Нет || || \ | [Object](*object) | Описание умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе [Об умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md). | Нет || |#
**Объект `properties`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || \ | [Object](*object) | Описание свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе [О свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). | Нет || || \ | [Object](*object) | Описание свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе [О свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). | Нет || |#
**Объект `device_info`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || manufacturer | [String](*string) | Название производителя устройства. Может содержать до 256 символов. Параметр является обязательным для описания официального навыка (подробнее в разделе [Обзор](https://yandex.ru/dev/dialogs/smart-home/doc/ru/about.md)). | Да, для [официальных навыков](https://yandex.ru/dev/dialogs/smart-home/doc/ru/certification.md) || || model | [String](*string) | Название модели устройства. Может содержать до 256 символов.Параметр является обязательным для описания официального навыка (подробнее в разделе [Обзор](https://yandex.ru/dev/dialogs/smart-home/doc/ru/about.md)). | Да, для [официальных навыков](https://yandex.ru/dev/dialogs/smart-home/doc/ru/certification.md) || || hw_version | [String](*string) | Версия аппаратной составляющей устройства. Может содержать до 256 символов. | Нет || || sw_version | [String](*string) | Версия программного обеспечения устройства. Может содержать до 256 символов. | Нет || |# - Ответ с ошибкой ```json translate=no HTTP/1.1 404 Not Found ``` [Глобальные коды](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/response-codes.md#enq-with-error-codes) {% endlist %} ## Поля `retrievable` и `reportable` в описании умений и свойств {#retrievable-reportable} В описании каждого умения и каждого свойства передаются два необязательных поля. Они определяют, как платформа умного дома узнает актуальное состояние: по запросу, уведомлением или обоими способами. **В объекте `capabilities`** #| || **Поле** | **Тип** | **Описание** | **Обязательность** || || `retrievable` | Boolean | Указывает, может ли платформа запросить текущее состояние умения через запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). - `true` (по умолчанию) — состояние умения доступно для запроса. Платформа отправляет `query` и ожидает актуальное значение в ответе. - `false` — состояние умения недоступно для запроса. Платформа не запрашивает состояние этого умения, а полагается только на уведомление `/callback/state`. Если поле не указано, по умолчанию используется `true`. | Нет || || `reportable` | Boolean | Указывает, должно ли изменение состояния этого умения доставляться через [сервис уведомлений](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/resources-alerts.md) (уведомление `/callback/state`). - `true` — изменение состояния умения доставляется уведомлением `/callback/state`, в том числе если оно произошло без команды со стороны Яндекса: физической кнопкой, пультом, из приложения провайдера, локальным сценарием провайдера. - `false` (по умолчанию) — изменение состояния умения не требуется отправлять уведомлением. Платформа получает актуальное состояние через запрос `query`, который отправляется по действию пользователя. Если поле не указано, по умолчанию используется `false`. Если у умения одновременно `retrievable: false` и `reportable: false`, платформа не получает актуальное состояние ни одним из способов. | Нет || |#
**В объекте `properties`** #| || **Поле** | **Тип** | **Описание** | **Обязательность** || || `retrievable` | Boolean | Указывает, может ли платформа запросить текущее значение свойства через запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). - `true` (по умолчанию) — значение свойства доступно для запроса. Платформа отправляет `query` и ожидает актуальное значение в ответе. - `false` — значение свойства недоступно для запроса. Платформа не запрашивает значение этого свойства, а полагается только на уведомление `/callback/state`. Значение допустимо, только если у свойства `reportable: true`. Если поле не указано, по умолчанию используется `true`. | Нет || || `reportable` | Boolean | Указывает, должно ли изменение значения этого свойства доставляться через [сервис уведомлений](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/resources-alerts.md) (уведомление `/callback/state`). - `true` — новое значение свойства доставляется уведомлением `/callback/state` при срабатывании датчика и при изменении его показаний. - `false` (по умолчанию) — изменение значения свойства не требуется отправлять уведомлением. Платформа получает актуальное значение через запрос `query`, который отправляется по действию пользователя. Если поле не указано, по умолчанию используется `false`. | Нет || |# {% note warning %} С 1 декабря 2026 года изменение каждого умения и каждого свойства, у которых указано `reportable: true`, должно доставляться в платформу умного дома запросом [Уведомление об изменении состояния устройства](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md) — `POST /api/v1/skills/{skill_id}/callback/state`. Событие отправляется по факту его наступления, без ожидания запроса со стороны Яндекса. Ответы на запросы [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md) и [Изменение состояния у устройств](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-action.md) уведомление не заменяют. Исчерпывающий перечень событий, при которых нужно отправлять уведомление, см. в разделе [Требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md). {% endnote %} Поля `retrievable` и `reportable` описывают отдельное умение или отдельное свойство. Не путайте их с полем `status_info.reportable`, которое относится к устройству целиком и отвечает за передачу статуса доступности `online` и `offline`. Подробнее см. в разделе [Информация об устройствах пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md). ## Пример {#example-JSON} В примере описаны свойства светильника с регулировкой цвета. > {% list tabs %} > > - Запрос > > > ```bash translate=no > curl -i -X GET 'https://example.com/v1.0/user/devices' \ > -H 'Authorization: Bearer 123qwe456a...' \ > -H 'X-Request-Id: ff36a3cc-ec...' > ``` > > > - Успешный ответ > > > ```json translate=no > HTTP/1.1 200 OK > > { > "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", > "payload": { > "user_id": "Misha-01-super-545", > "devices": [{ > "id": "abc-123", > "name": "лампa", > "status_info": { > "reportable": true > }, > "description": "цветная лампа", > "room": "спальня", > "type": "devices.types.light", > "custom_data": { > "foo": 1, > "bar": "two", > "baz": false, > "qux": [1, "two", false], > "quux": { > "quuz": { > "corge": [] > } > } > }, > "capabilities": [{ > "type": "devices.capabilities.range", > "retrievable": true, > "parameters": { > "instance": "brightness", > "unit": "unit.percent", > "range": { > "min": 0, > "max": 100, > "precision": 10 > } > } > }, > { > "type": "devices.capabilities.on_off" > }, > { > "type": "devices.capabilities.color_setting", > "parameters": { > "color_model": "hsv", > "temperature_k": { > "min": 2700, > "max": 9000, > "precision": 1 > } > } > } > ], > "device_info": { > "manufacturer": "Provider2", > "model": "hue g11", > "hw_version": "1.2", > "sw_version": "5.4" > } > } > > ] > } > } > ``` > > > - Ответ с ошибкой > > > ```json translate=no > HTTP/1.1 401 Unauthorized > ``` > > {% endlist %} [![Служба поддержки](../_images/support-image.svg)](https://yandex.ru/dev/dialogs/smart-home/doc/ru/feedback.md) [*object]: Список пар `"ключ": значение`, разделенных запятой. Выделяется фигурными скобками `{}`. ```json translate=no { "name": "John", "surname": "Smith" } ``` [*string]: Cтрока, выделяется кавычками, например `"Hello world"`. [*array]: Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, `true`, `false`, объект или массив. Массив выделяется квадратными скобками `[]`: ```json translate=no "cities": ["Moscow", "Tokyo", "New York"] ``` [*boolean]: Логическое значение без кавычек: `true` (истина) или `false` (ложь).