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 awarii 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 kilka przykładów odpowiedzi na intencje, które obsługują błędy. W sekcji Błędy i wyjątki znajdziesz prawidłowe wartości parametru 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 intencję EXECUTEna adres URL usługi. Okazało się, że urządzenia użytkownika są offline i nie można nimi sterować, więc Twoja realizacja zwraca odpowiedź EXECUTE z wartościami 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ć odpowiedź EXECUTE 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 APIreportStateAndNotifications:

Ten przykład pokazuje, jak wysłać aktywne powiadomienie z wartością 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 „Drzwi urządzenia są otwarte”. Możesz wysyłać odpowiednie stany urządzenia wraz z powiadomieniami w tym samym pakiecie.

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 drzwi garażowych, ale podczas zamykania drzwi się zacinają. 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 dotyczącej błędów i wyjątków.