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

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

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

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

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