Как обрабатывать ошибки и исключения

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

В этом руководстве приведены примеры ответов на намерения, которые обрабатывают ошибки. Чтобы узнать, какие значения errorCode допустимы для ошибок и исключений, ознакомьтесь с разделом Ошибки и исключения.

Пример 1. Ответ с ошибкой для намерения EXECUTE

У конечного пользователя в гостиной установлены два умных светильника. Пользователь произносит команду "включи свет в гостиной", и Google отправляет на URL выполнения запроса намерение EXECUTE. Вы обнаружили, что устройства пользователя офлайн и ими нельзя управлять, поэтому ваш сервис возвращает ответ EXECUTE с status ERROR и errorCode deviceOffline.

В этом примере показано, как вернуть ответ EXECUTE с errorCode от устройства с ограниченными возможностями, как описано выше:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

После получения ответа Google Assistant показывает пользователю сообщение "Устройство сейчас недоступно". Помните, что после отправки errorCode deviceOffline в ответе EXECUTE вам все равно нужно отправлять данные о состоянии офлайн для устройств в состоянии отчета.

Пример 2. Исключение без блокировки для намерения EXECUTE

Пользователь пытается заблокировать умный замок на входной двери с помощью устройства Assistant. Вы успешно заблокировали дверь, но обнаружили, что заряд батареи устройства низкий, поэтому в ответе на запрос выполнения возвращается код EXECUTE с параметрами status SUCCESS и exceptionCode lowBattery.

В этом примере показано, как отправить ответ EXECUTE с exceptionCode от устройства блокировки, как описано выше:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

После получения ответа Assistant показывает пользователю сообщение "У устройства низкий заряд батареи".

Пример 3. Проактивные уведомления об ошибках

В некоторых случаях полезно предупреждать пользователей об ошибках, особенно если они ожидают, что функция будет выполнена автоматически. Для трейтов, поддерживающих умные уведомления, вы можете заблаговременно уведомлять пользователя о возникновении ошибки, если вы реализовали smart home умные уведомления.

Умная сушильная машина работает, и кто-то открывает дверцу до окончания цикла. Вы можете вызвать метод Google Home Graph API reportStateAndNotifications, чтобы отправить проактивное уведомление с помощью errorCode:

В примере ниже показано, как отправить активное уведомление с помощью errorCode от сушильной машины, как описано выше:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

После получения уведомления Assistant предлагает пользователю: "Дверь устройства открыта". Вы можете отправлять соответствующие состояния устройств вместе с уведомлениями в одной полезной нагрузке.

Пример 4. Уведомление с напоминанием

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

Пользователь отдает команду закрыть гаражные ворота, но они заклинивают. Вы можете отправить повторное уведомление с errorCode:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

После получения уведомления Assistant показывает пользователю сообщение "Устройство заблокировано". Вы можете отправлять соответствующие состояния устройств вместе с уведомлениями в одном объекте payload.

Подробную информацию и errorCodes можно найти в справочной документации по ошибкам и исключениям.