On_off

devices.capabilities.on_off

Удаленное включение и выключение устройства (аналог нажатия кнопки питания на устройстве или его пульте управления). Является базовым умением для большинства устройств.

Общие голосовые команды

Для большинства устройств используются отдельные команды включения и выключения. Голосовые команды зависят от типа устройства и приведены в описании соответствующих типов.

Алиса, включи свет.
Алиса, поставь чайник.

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

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

Параметры умения

Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
retrievable	Boolean	Доступен ли для данного умения устройства запрос состояния. Допустимые значения: `true` — для умения доступен запрос состояния. Является значением по умолчанию; `false` — для умения недоступен запрос состояния.	Нет
reportable	Boolean	Признак включенного оповещения об изменении состояния умения при помощи сервиса уведомлений. Допустимые значения: `true` — оповещение включено. Производитель оповещает платформу умного дома о каждом изменении состояния умения; `false` — оповещение выключено. Производитель не оповещает платформу об изменении состояния умения. Является значением по умолчанию.	Нет
parameters	Object	Объект `parameters`.	Нет

Объект parameters

Параметр

Тип

Описание

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

split

Boolean

Параметр используется совместно с retrievable:false и показывает, что за включение/выключение устройства у провайдера отвечают разные команды. На главном экране приложения Дом с Алисой у поддерживаемых устройств будет показана опция включения. Допустимые значения:

true — за включение и выключение отвечают разные команды;
false — за включение и выключение отвечает одна команда. Является значением по умолчанию.

Нет

Пример использования

Платформа умного дома отправляет провайдеру запрос на получение информации об устройствах пользователя. Провайдер в ответ передает информацию о том, что у пользователя есть розетка с удаленным включением и выключением.

Запрос

Ответ

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "user_id": "user-001",
        "devices": [
            {
                "id": "socket-001-xda",
                "name": "розетка",
                "description": "умная розетка xda",
                "room": "спальня",
                "type": "devices.types.socket",
                "custom_data": {
                    "api_location": "rus"
                },
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "retrievable": false,
                        "reportable": false,
                        "parameters": {
                            "split": false
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider-01",
                    "model": "xda 1",
                    "hw_version": "1.2",
                    "sw_version": "5.4"
                }
            }
        ]
    }
}

Текущее состояние умения

Структура используется в ответе операции Информация о состояниях устройств пользователя и в теле запроса операции Уведомление об изменении состояний устройств.

Параметры умения

Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Параметры состояния умения.	Да

Объект state

Параметр

Тип

Описание

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

instance

String

Название функции для данного умения. Допустимые значения:

on — удаленное включение и выключение устройства.

Да

value

Boolean

Значение функции для данного умения. Допустимые значения:

true — устройство включено;
false — устройство выключено.

Да

Пример использования

Платформа умного дома отправляет провайдеру запрос о состоянии устройств пользователя. Провайдер в ответ передает информацию о состоянии устройств пользователя.

Запрос

Ответ

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' \
-d '{
      "devices":
      [
        {
            "id": "socket-001-xda",
            "custom_data": {
                "api_location": "rus"
            }
        }
      ]
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "socket-001-xda",
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "state": {
                            "instance": "on",
                            "value": true
                        }
                    }
                ]
            }
        ]
    }
}

Изменение состояния умения у устройства

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

Параметры умения

Параметр	Тип	Описание	Обязательный
type	String	Тип умения.	Да
state	Object	Объект, который описывает результат изменения состояния умения.	Да

Объект state

Параметр

Тип

Описание

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

instance

String

Название функции для данного умения. Допустимые значения:

on — удаленное включение и выключение устройства.

Да

action_result

Object

Результат изменения состояния умения устройства.

Нет

Объект action_result

Параметр	Тип	Описание	Обязательный
status	String	Статус изменения состояния умения устройства. Допустимые значения: `DONE` — состояние умения устройства успешно изменено; `ERROR` — при изменении состояния умения устройства произошла ошибка.	Да
error_code	String	Код возможной ошибки из списка ошибок. Если `status:"ERROR"`, параметр является обязательным.	Нет
error_message	String	Расширенное человекочитаемое описание возможной ошибки. Отображается только в разделе Тестирование в консоли разработчика.	Нет

Пример использования

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

Запрос

Ответ

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' \
-d '{
      "payload": {
        "devices":
        [
          {
            "id": "socket-001-xda",
            "custom_data": {
              "api_location": "rus"
            },
            "capabilities": [
              {
                 "type": "devices.capabilities.on_off",
                 "state": {
                   "instance": "on",
                   "value": false
                 }
              }
            ]
          }
        ]
      }
    }'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [
            {
                "id": "socket-001-xda",
                "capabilities": [
                    {
                        "type": "devices.capabilities.on_off",
                        "state": {
                            "instance": "on",
                            "action_result": {
                                "status": "DONE"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

Список пар "ключ": значение, разделенных запятой. Выделяется фигурными скобками {}.

{
  "name": "John",
  "surname": "Smith"
}

Была ли статья полезна?

Об умениях

Color_setting