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 przykłady 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ę EXECUTEdo adresu 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 na 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 wartościami 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 powinny działać 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 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 ł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ę zacina. 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ółów errorCodes znajdziesz w dokumentacji referencyjnej Błędy i wyjątki.