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