Уведомление об изменении состояния устройства

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

Пример ситуации, в которой отправляется текущий запрос: пользователь прошел мимо датчика движения, датчик сработал.

Исчерпывающий перечень событий, при которых отправка этого запроса обязательна, — в разделе Требования к уведомлениям.

Формат запроса

POST https://dialogs.yandex.net/api/v1/skills/{skill_id}/callback/state

Заголовки запроса

Формат тела запроса

{
    "ts": Float,
    "payload": {
        "user_id": String,
        "devices": [{
            "id": String,
            "status": String,
            "capabilities": [
                "<capability1>": Object,
                "<capability2>": Object
                    ...
                    ],
            "properties": [
                "<property1>": Object,
                "<property2>": Object
                    ...
                    ]
        }]
    }
}

Объект payload

Объект devices

Объект capabilities

Объект properties

Что должно быть в объекте devices

В объекте каждого устройства из массива devices обязательно передать хотя бы одно из:

• status — изменение доступности устройства (online или offline);
• непустой массив capabilities — изменение состояния умений;
• непустой массив properties — изменение показаний свойств.

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

Допускается запрос, содержащий только status, — например, при потере или восстановлении связи с устройством, когда состояние умений и свойств не изменилось.

Требования к ts

Поле ts содержит время возникновения события, а не время отправки уведомления. Формат — unix timestamp в секундах (дробное число).

• Платформа использует ts для упорядочивания событий. Значение ts должно быть монотонным для каждого устройства: ts последующего события не должен быть меньше ts предыдущего.
• Если платформа получает уведомление с устаревшим ts (меньшим, чем у уже обработанного события для того же устройства), такое событие игнорируется.
• Не используйте ts для задержки отправки — событие отправляется по факту его наступления.
• Часы на серверах провайдера должны быть синхронизированы. Значение ts из будущего приведет к тому, что последующие события будут отброшены как устаревшие.

Формат ответа

HTTP/1.1 202 Accepted

{
  "request_id": String,
  "status": "ok"
}

HTTP/1.1 400

{
  "request_id": String,
  "status": "error",
  "error_code": String,
  "error_message": String
}

Обработка ошибок и повторные запросы

Навык должен обрабатывать ответ платформы на свой запрос в соответствии с таблицей ниже.

Принятое уведомление платформа подтверждает кодом 202 Accepted. Код 200 OK в ответ на запрос в сервис уведомлений не возвращается.

При повторной отправке не нужно:

• повторять запрос, отклоненный с BAD_REQUEST или UNKNOWN_USER, — он будет отклонен снова;
• подставлять новое значение ts — при повторе передается исходное время события;
• отправлять уведомление об изменении, которого не было, — например, повторно отправлять последнее состояние по таймеру.

Если после нескольких повторов доставить событие не удалось, отправьте актуальное состояние устройства новым уведомлением с новым ts, а не копию устаревшего события.

Примеры

Переход в offline

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703322.1,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "lamp-001",
            "status": "offline"
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "75442486-0878-440c-9db1-a7006c25a39f",
  "status": "ok"
}

Возврат в online

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703400.5,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "lamp-001",
            "status": "online"
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "a1b2c3d4-5678-90ef-1234-567890abcdef",
  "status": "ok"
}

Изменение состояния умения

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703500.0,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "lamp-001",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "b2c3d4e5-6789-01ab-cdef-234567890abc",
  "status": "ok"
}

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

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703600.0,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "sensor-001-snsr",
            "properties": [{
                "type": "devices.properties.event",
                "state": {
                    "instance": "motion",
                    "value": "detected"
                }
            }]
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "c3d4e5f6-7890-12ab-cdef-34567890abcd",
  "status": "ok"
}

Одновременное изменение статуса и состояния

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703700.0,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "lamp-001",
            "status": "online",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }],
            "properties": [{
                "type": "devices.properties.float",
                "state": {
                    "instance": "temperature",
                    "value": 23.5
                }
            }]
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "d4e5f6a7-8901-23ab-cdef-4567890abcde",
  "status": "ok"
}

Успешный ответ — 202 Accepted

HTTP/1.1 202 Accepted

{
  "request_id": "75442486-0878-440c-9db1-a7006c25a39f",
  "status": "ok"
}

Ответ с ошибкой

HTTP/1.1 400

{
  "request_id": "same-as-in-request",
  "status": "error",
  "error_code": "UNKNOWN_USER",
  "error_message": "User not found"
}

Как обрабатывать ответ платформы, см. в разделе Обработка ошибок и повторные запросы.

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

"cities": ["Moscow", "Tokyo", "New York"]