---
metadata:
- name: generator
content: Diplodoc Platform v5.66.0
alternate:
- https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md
- https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md
- href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.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://alice.yandex.ru/smart-home) и хочет поменять состояние устройств.
В ответ на такой запрос провайдеру необходимо вернуть состояния запрошенных устройств пользователя.
{% note info %}
Умения, для которых запрос состояния недоступен (имеющие атрибут `retrievable=false`), можно не включать в ответ, так как их состояние будет проигнорировано.
{% endnote %}
{% note info "Уведомление не заменяется ответом на query" %}
Запрос `query` вызывается по действию пользователя и не содержит поля статуса доступности, поэтому статус «не в сети» через него не передается.
Ответы на `query` не заменяют уведомление [об изменении состояния устройства](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md) (`/callback/state`):
- изменение, произошедшее физически или в приложении провайдера, должно доставляться без запроса со стороны Яндекса;
- значение в последующем ответе `query` должно совпадать с последним состоянием, переданным уведомлением `/callback/state`.
Подробнее см. в разделе [Требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md).
{% endnote %}
## Формат запроса платформы умного дома {#input}
Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).
```bash translate=no
POST https://example.com/v1.0/user/devices/query
```
#### Заголовки запроса {#headers}
#|
||
**Заголовок** | **Описание** | **Обязательный**
||
||
Authorization
|
Авторизационный токен пользователя.
|
Да
||
||
Content-Type
|
Формат передаваемых/отправляемых данных. Возможные значения: application/json.
|
Да, в операциях с http-методом POST
||
||
X-Request-Id
|
Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем.
|
Да
||
|#
#### Формат тела запроса {#structure-in}
```json translate=no
{
"devices": [
{
"id": String,
"custom_data": Object
},
...
]
}
```
#|
||
**Параметр**
|
**Тип**
|
**Описание**
|
**Обязательный**
||
||
devices
|
[Array](*array) of [objects](*object)
|
Массив с устройствами пользователя.
|
Да
||
|#
**Объект `devices`**
#|
||
**Параметр**
|
**Тип**
|
**Описание**
|
**Обязательный**
||
||
id
|
[String](*string)
|
Идентификатор устройства. Должен быть уникален среди всех устройств производителя.
|
Да
||
||
custom_data
|
[Object](*object)
|
Объект, который был передан провайдером для устройства в ответе на запрос [Информация об устройствах пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md).
|
Нет
||
|#
## Формат ответа провайдера {#output-structure}
Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.
{% list tabs %}
- Успешный ответ
```json translate=no
HTTP/1.1 200 OK
{
"request_id": String,
"payload": {
"devices":[
{
"id": String,
"capabilities": [
"": Object,
"": Object,
...
],
"properties": [
"": Object,
"": Object,
...
],
"error_code": String,
"error_message": String
},
...
]
}
}
```
#|
||
**Параметр**
|
**Тип**
|
**Описание**
|
**Обязательный**
||
||
request_id
|
[String](*string)
|
Идентификатор запроса.
|
Да
||
||
payload
|
[Object](*object)
|
Объект с устройствами.
|
Да
||
|#
**Объект `payload`**
#|
||
**Параметр**
|
**Тип**
|
**Описание**
|
**Обязательный**
||
||
devices
|
[Array](*array) of [objects](*object)
|
Массив с устройствами пользователя.
|
Да
||
|#
**Объект `devices`**
#|
||
**Параметр**
|
**Тип**
|
**Описание**
|
**Обязательный**
||
||
id
|
[String](*string)
|
Идентификатор устройства. Должен быть уникален среди всех устройств производителя.
|
Да
||
||
capabilities
|
[Array](*array) of [objects](*object)
|
Массив с информацией об [умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md) устройства.
|
Нет
||
||
properties
|
[Array](*array) of [objects](*object)
|
Массив с информацией о [свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md) устройства.
|
Нет
||
||
error_code
|
[String](*string)
|
Код возможной ошибки из [списка](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/response-codes.md#codes-api). Если поле непустое, параметры `capabilities` и `properties` будут проигнорированы.
|
Нет
||
||
error_message
|
[String](*string)
|
Расширенное человекочитаемое описание возможной ошибки. Доступно в консоли разработчика на вкладке [Тестирование](https://yandex.ru/dev/dialogs/smart-home/doc/ru/testing.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).
|
Нет
||
|#
[Коды, связанные с запросом](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/response-codes.md#codes-api)
- Ответ с ошибкой
```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 %}
## Пример {#example-JSON}
В примере описаны свойства светильника с регулировкой цвета и розетки.
> {% list tabs %}
>
> - Запрос
>
>
> ```bash translate=no
> curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
> -H 'Authorization: Bearer 123qwe456a...' \
> -H 'X-Request-Id: ff36a3cc-ec...' \
> -H 'Content-Type: application/json'
> ```
>
> Тело запроса
>
> ```json translate=no
> {
> "devices": [
> {
> "id": "abc-123",
> "custom_data": {
> "foo": 1,
> "bar": "two",
> "baz": false,
> "qux": [1, "two", false],
> "quux": {
> "quuz": {
> "corge": []
> }
> }
> }
> },
> {
> "id": "sock-56GF-3"
> }
> ]
> }
> ```
>
>
> - Успешный ответ
>
>
> ```json translate=no
> {
> "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
> "payload": {
> "devices": [{
> "id": "abc-123",
> "capabilities": [{
> "type": "devices.capabilities.color_setting",
> "state": {
> "instance": "hsv",
> "value": {
> "h": 255,
> "s": 50,
> "v": 100
> }
> }
> }, {
> "type": "devices.capabilities.on_off",
> "state": {
> "instance": "on",
> "value": true
> }
> }]
> },
> {
> "id": "abc-123",
> "error_code": "DEVICE_NOT_FOUND",
> "error_message": "the human readable error message"
> },
> {
> "id": "sock-56GF-3",
> "capabilities": [{
> "type": "devices.capabilities.on_off",
> "state": {
> "instance": "on",
> "value": true
> }
> }]
> }]
> }
> }
> ```
>
>
> - Ответ с ошибкой
>
>
> ```json translate=no
> HTTP/1.1 404 Not Found
> ```
>
> {% endlist %}
[](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"]
```