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

l10n

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

В этом руководстве представлены некоторые примеры ответов о намерениях, которые обрабатывают ошибки. См. раздел Ошибки и исключения , чтобы просмотреть допустимые значения 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 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 см. в справочной документации по ошибкам и исключениям .