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

Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest, aby zapewnić użytkownikom odpowiednią obsługę błędów i komunikację, dzięki czemu będą wiedzieć, co się stało, a w miarę możliwości także, jak to naprawić. Zastanów się nad możliwymi scenariuszami niepowodzenia i tym, jak urządzenie powinno na nie reagować: co się stanie, jeśli użytkownik przerwie trwające zadanie? Co się stanie, jeśli użytkownik poprosi o wykonanie działania na urządzeniu, które jest offline? Planowanie rozwiązań tych problemów i pomaganie użytkownikom w ich przezwyciężaniu może zapobiec frustracji i zapewnić wyższą jakość korzystania z urządzeń.

W tym przewodniku znajdziesz przykłady odpowiedzi na intencje, które obsługują błędy. W sekcji Błędy i wyjątki znajdziesz prawidłowe wartości errorCode dla błędów i wyjątków.

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

Użytkownik ma w salonie 2 inteligentne lampy. Użytkownik wydaje polecenie „włącz światła w salonie”, a Google wysyła EXECUTEintencję na adres URL realizacji. Okazało się, że urządzenia użytkownika są offline i nie można nimi sterować, więc Twoja realizacja zwraca odpowiedź EXECUTE z status ERROR i errorCode deviceOffline.

Ten przykład pokazuje, jak zwrócić odpowiedź EXECUTE z errorCode z urządzenia oświetleniowego, 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"
      }
    ]
  }
}

Po otrzymaniu odpowiedzi Google Assistant wyświetla użytkownikowi komunikat „urządzenie jest obecnie niedostępne”. Pamiętaj, że po wysłaniu errorCode deviceOffline w odpowiedzi EXECUTE nadal musisz wysyłać stan offline urządzeń w stanie raportu.

Przykład 2. Wyjątek nieblokujący dla intencji EXECUTE

Użytkownik próbuje zamknąć inteligentny zamek w drzwiach wejściowych za pomocą Assistant. Możesz skutecznie sterować zamkiem, ale bateria urządzenia jest słaba, więc realizacja zwraca odpowiedź EXECUTE z status SUCCESS i exceptionCode lowBattery.

Ten przykład pokazuje, jak wysłać EXECUTE odpowiedź z exceptionCode z zablokowanego urządzenia, 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 Assistant wyświetla użytkownikowi komunikat „Urządzenie ma niski poziom baterii”.

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

W niektórych przypadkach warto powiadomić użytkowników o błędzie, zwłaszcza w przypadku funkcji, które użytkownicy oczekują, że zostaną wykonane automatycznie. W przypadku cech, które obsługują aktywne powiadomienia, możesz aktywnie powiadamiać użytkownika o wystąpieniu błędu, jeśli masz wdrożone smart home aktywne powiadomienia.

Inteligentna suszarka jest włączona, a ktoś otwiera drzwi przed zakończeniem cyklu. Aby wysłać aktywne powiadomienie z errorCode, możesz wywołać metodę Google Home Graph interfejsu API:reportStateAndNotifications

Ten przykład pokazuje, jak wysłać aktywne powiadomienie z errorCode z suszarki zgodnie z opisem powyżej:

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świetla użytkownikowi komunikat „the device door is opened” (drzwiczki urządzenia zostały otwarte). Odpowiednie stany urządzenia możesz wysyłać razem z powiadomieniami w tym samym ładunku.

Przykład 4. Powiadomienie uzupełniające

W przypadku poleceń dotyczących cech, które obsługują powiadomienia uzupełniające, możesz wysłać użytkownikowi powiadomienie uzupełniające, gdy wystąpi błąd lub wyjątek, jeśli masz wdrożone smart home powiadomienia uzupełniające.

Użytkownik wydaje polecenie zamknięcia bramy garażowej, ale podczas zamykania brama się zacięła. Możesz wysłać powiadomienie uzupełniające z 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
        }
      }
    }
  }
}

Po otrzymaniu powiadomienia Assistant wyświetla użytkownikowi komunikat „Urządzenie jest zablokowane”. Możesz wysyłać odpowiednie stany urządzenia wraz z powiadomieniami w tym samym ładunku.

Więcej informacji i szczegółowe errorCodes znajdziesz w dokumentacji referencyjnej Błędy i wyjątki.