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

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

В этом руководстве приведены примеры ответов на намерения, которые обрабатывают ошибки. Допустимые значения 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 сообщает пользователю, что устройство сейчас недоступно. Помните, что вам по-прежнему нужно отправлять статус офлайн для устройств в reportState после отправки 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 сообщает пользователю, что устройство заблокировано. Вы можете отправлять соответствующие состояния устройств с уведомлениями в одной полезной нагрузке.

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