--- metadata: - name: generator content: Diplodoc Platform v5.66.0 alternate: - https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-action.md - https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-action.md - href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-action.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 # Изменение состояния у устройств Изменяет текущее состояние устройств пользователя. Пример ситуации, в которой отправляется текущий запрос: пользователь зашел в приложение [![](../_images/smart-home-app.svg) Дом с Алисой](https://alice.yandex.ru/smart-home) и хочет поменять состояние устройств. В ответ на такой запрос провайдеру необходимо изменить состояния запрошенных устройств пользователя. {% note info "Ответ на команду не заменяет уведомление" %} Если провайдер принимает `action` на асинхронную обработку и отвечает до фактического выполнения, фактическое состояние обязательно передается уведомлением [об изменении состояния устройства](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md) (`/callback/state`). При синхронном выполнении с немедленным результатом отдельное уведомление не требуется. Примеры: - Синхронное выполнение — переключение реле или розетки: команда выполняется мгновенно, результат возвращается в ответе на `action`. Отдельное уведомление не требуется. - Асинхронное выполнение — разогрев чайника, старт уборки пылесосом, открытие шторы: провайдер принимает команду в обработку и отвечает до фактического выполнения. Фактическое состояние передается уведомлением `/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/action ``` #### Заголовки запроса {#headers} #| || **Заголовок** | **Описание** | **Обязательный** || || Authorization | Авторизационный токен пользователя. | Да || || Content-Type | Формат передаваемых/отправляемых данных. Возможные значения: application/json. | Да, в операциях с http-методом POST || || X-Request-Id | Идентификатор запроса. Необходимо логировать на стороне провайдера для расследования инцидентов и проблем. | Да || |# #### Формат тела запроса {#structure-in} ```json translate=no { "payload": { "devices":[ { "id": String, "custom_data": Object, "capabilities": [ "": Object, "": Object, ... ] } ] } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || payload | [Object](*object) | Объект с устройствами. | Да || |#
**Объект `payload`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || 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). Состоит из набора пар `"ключ":"значение"` любой вложенности и представляет собой дополнительную информацию об устройстве. Содержимое объекта не должно превышать 1024 байт. | Нет || || capabilities | [Array](*array) of [objects](*object) | Массив с информацией об [умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.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). | Да || |# ## Формат ответа провайдера {#output-structure} Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату. {% list tabs %} - Успешный ответ ```json translate=no HTTP/1.1 200 OK { "request_id": String, "payload": { "devices": [ { "id": String, "capabilities": [ "": Object, "": Object, ... ], "action_result": { "status": String, "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) устройства. | Да, если отсутствует `action_result` || || action_result | [Object](*object) | Результат изменения состояния у устройства. Параметр является обязательным, если отсутствует `capabilities`. {% note info %} Рекомендуется возвращать параметр для каждого умения по отдельности. Если такой возможности нет, возвращайте результат для всего устройства. Ответ на запрос считается успешным (`status:"DONE"`), если хотя бы одно состояние у устройства изменилось. {% endnote %} | Да, если отсутствует `capabilities` || |#
**Объект `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). | Нет || |#
**Объект `action_result`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || status | [String](*string) | Статус изменения состояния у устройства. Допустимые значения: - `DONE` — состояние устройства успешно изменено; - `ERROR` — при изменении состояния у устройства произошла ошибка. | Нет || || 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). | Нет || |# [Коды, связанные с запросом](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/action' \ > -H 'Authorization: Bearer 123qwe456a...' \ > -H 'X-Request-Id: ff36a3cc-ec...' \ > -H 'Content-Type: application/json' > ``` > > Тело запроса > > ```json translate=no > { > "payload": { > "devices": [{ > "id": "abc-123", > "custom_data": { > "foo": 1, > "bar": "two", > "baz": false, > "qux": [1, "two", false], > "quux": { > "quuz": { > "corge": [] > } > } > }, > "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": false > } > }] > }, { > "id": "sock-56GF-3", > "capabilities": [{ > "type": "devices.capabilities.on_off", > "state": { > "instance": "on", > "value": false > } > }] > }] > } > } > ``` > > > - Успешный ответ > > > ```json translate=no > HTTP/1.1 200 OK > > { > "request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3", > "payload": { > "devices": [{ > "id": "abc-123", > "capabilities": [{ > "type": "devices.capabilities.color_setting", > "state": { > "instance": "hsv", > "action_result": { > "status": "ERROR", > "error_code": "INVALID_ACTION", > "error_message": "the human readable error message" > } > } > }, > { > "type": "devices.capabilities.on_off", > "state": { > "instance": "on", > "action_result": { > "status": "DONE" > } > } > }] > }, > { > "id": "sock-56GF-3", > "action_result": { > "status": "ERROR", > "error_code": "DEVICE_UNREACHABLE" > } > }] > } > } > ``` > > > - Ответ с ошибкой > > > ```json translate=no > HTTP/1.1 404 Not Found > ``` > > {% 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"] ```