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ę, aby wiedzieli, co się stało i jak to naprawić. Zastanów się nad możliwymi scenariuszami awarii i tym, jak urządzenie powinno na nie reagować. Co się stanie, jeśli użytkownik przerwie wykonywanie zadania? Co się stanie, jeśli użytkownik poprosi o wykonanie działania na urządzeniu, gdy jest ono offline? Planowanie takich problemów i pomaganie użytkownikom w ich rozwiązywaniu może zapobiec frustracji i zapewnić lepsze wrażenia z korzystania z urządzeń.

W tym przewodniku znajdziesz kilka przykładów odpowiedzi na intencje, które obsługują błędy. Więcej informacji o prawidłowych wartościach errorCode w przypadku błędów i wyjątków znajdziesz w sekcji Błędy i wyjątki.

Przykład 1. Odpowiedź na błąd w przypadku intencji EXECUTE

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

Ten przykład pokazuje, jak zwrócić odpowiedź EXECUTE z kodem błędu 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 "device są obecnie niedostępne". Pamiętaj, że nadal musisz wysłać stan offline urządzeń w raporcie po wysłaniu errorCode deviceOffline w odpowiedzi EXECUTE.

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

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

Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE z kodem wyjątku 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 Asystent wyświetla użytkownikowi komunikat „device ma słabą baterię”.Assistant

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 będą wykonywane automatycznie. W przypadku cech, które obsługują aktywne powiadomienia, możesz aktywnie powiadamiać użytkownika o błędzie, jeśli masz wdrożone smart home aktywne powiadomienia.

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

Ten przykład pokazuje, jak wysłać aktywne powiadomienie z kodem błędu 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świetla użytkownikowi komunikat „the device door is opened”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń wraz z powiadomieniami.

Przykład 4. Powiadomienie uzupełniające

W przypadku poleceń cech, które obsługują powiadomienia uzupełniające, możesz wysłać powiadomienie uzupełniające do użytkownika, 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 brama zacina się podczas zamykania. Możesz wysłać powiadomienie uzupełniające z kodem błędu 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 „device is jammed”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń wraz z powiadomieniami.

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