Обработка ошибок и исключений

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

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

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

У конечного пользователя в гостиной установлены два умных светильника. Пользователь подаёт команду «включить свет в гостиной», и Google отправляет намерение EXECUTE на ваш URL-адрес выполнения. Вы обнаружили, что устройства пользователя отключены от сети и не управляются, поэтому ваш URL-адрес выполнения возвращает ответ 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 .

Умная сушилка работает, и кто-то открывает дверцу до завершения цикла. Вы можете вызвать метод reportStateAndNotifications API Google Home Graph , чтобы отправить упреждающее уведомление с 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 выводит сообщение « Устройство заблокировано». Вы можете отправлять соответствующие состояния устройства вместе с уведомлениями в той же полезной нагрузке.

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