Obsługa błędów i wyjątków

Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest zapewnienie użytkownikom prawidłowej obsługi błędów i komunikacja, tak aby rozumieli, co się stało i jak można to naprawić. Zastanów się, jakie są możliwe scenariusze awarii, i jak będzie reagować urządzenie: co się stanie, jeśli użytkownik przerwie trwające zadanie? Co się stanie, jeśli użytkownik poprosi o wykonanie działania z urządzenia, gdy urządzenie jest offline? Planowanie tych problemów i pomaganie użytkownikom w odzyskaniu ich frustracji pozwala uniknąć frustracji użytkowników i sprawia, że Twoje urządzenia działają lepiej.

Ten przewodnik zawiera przykłady odpowiedzi na zamiary, które obsługują błędy. Prawidłowe wartości errorCode błędów i wyjątków znajdziesz w sekcji Błędy i wyjątki.

Przykład 1. Odpowiedź błędu w przypadku intencji EXECUTE

Użytkownik ma 2 inteligentne światła zainstalowane w salonie. Użytkownik wydaje polecenie „Włącz światło w salonie”, a Google wysyła intencję EXECUTE do Twojego adresu URL realizacji. Okazało się, że urządzenia użytkownika są offline i których nie można kontrolować, więc Twoja realizacja zwraca odpowiedź EXECUTE z tagami status ERROR i errorCode deviceOffline.

Ten przykład pokazuje, jak zwrócić odpowiedź EXECUTE z tagiem errorCode z urządzenia lekkiego, jak opisano wcześniej:

{
  "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 will prompt the user with "the device are not available right now" after receiving the response. Remember that you still need to send offline state for devices in report state after sending errorCode deviceOffline in EXECUTE response.

Przykład 2: wyjątek nieblokujący dla intencji EXECUTE

Użytkownik próbuje zablokować Smart Lock przy drzwiach wejściowych, używając urządzenia z systemem Assistant. Możesz skutecznie zablokować zamek, ale okaże się, że bateria urządzenia jest słaba, przez co realizacja będzie zwracać odpowiedź EXECUTE z status SUCCESS i exceptionCode lowBattery.

Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE z tagiem exceptionCode z urządzenia blokującego, jak opisano wcześniej:

{
  "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"
      }
    }]
  }
}

Po otrzymaniu odpowiedzi użytkownik Assistant wyświetli komunikat z komunikatem „Urządzenie ma niski poziom baterii”.

Przykład 3. Aktywne powiadomienia o błędach

W niektórych przypadkach może być przydatne ostrzeżenie użytkowników o błędach, zwłaszcza w przypadku funkcji, które użytkownicy mogą ukończyć automatycznie. W przypadku cech, które obsługują powiadomienia aktywne, możesz powiadomić użytkownika o ewentualnym błędzie, jeśli zastosujesz go.smart home proactive notifications.

Inteligentna suszarka działa, a ktoś otwiera drzwi przed zakończeniem cyklu. Możesz zadzwonić pod numer Google Home Graph API reportStateAndNotifications method to send a proactive notification with an errorCode:

Ten przykład pokazuje, jak wysłać aktywne powiadomienie z urządzeniem errorCode z suszarki, jak opisano wcześniej:

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
        }
      }
    }
  }
}

Po otrzymaniu powiadomienia Assistant wyświetli użytkownikowi komunikat „otwarte drzwi urządzenia”. Odpowiednie stany urządzenia możesz wysłać wraz z powiadomieniami w ramach tego samego ładunku.

Przykład 4. Powiadomienie

W przypadku poleceń cech, które obsługują dalsze powiadomienia, możesz wysłać użytkownikowi powiadomienie uzupełniające w przypadku wystąpienia błędu lub wyjątku, jeśli wdrożysz smart home dalsze powiadomienia.

Użytkownik wydaje polecenie zamknięcia drzwi do garażu, ale drzwi się zacięły podczas zamykania. Możesz wysłać dalsze powiadomienie za pomocą 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 otrzyma powiadomienie z komunikatem „urządzenie się zaciąło”. Za pomocą tego samego ładunku możesz też wysyłać odpowiednie stany urządzenia z powiadomieniami.

Więcej informacji i szczegółowe informacje na temat obiektu errorCodes znajdziesz w dokumentacji referencyjnej dotyczącej błędów i wyjątków.