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 dobrą obsługę błędów i komunikację, aby zrozumieli, co się stało i, jeśli to możliwe, 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 zadanie w trakcie jego wykonywania? Co się stanie, jeśli użytkownik poprosi o wykonanie działania na urządzeniu, gdy jest ono offline? Uwzględnienie tych problemów i pomoc użytkownikowi w ich rozwiązaniu może zapobiec frustracji użytkownika i zapewnić lepsze wrażenia podczas korzystania z urządzeń.

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

Przykład 1. Odpowiedź z błędem na intencję EXECUTE

Użytkownik ma w salonie zainstalowane 2 inteligentne źródła światła. Użytkownik wydaje polecenie „włącz światła w salonie”, a Google wysyła intencję EXECUTE na Twój adres URL realizacji. Urządzenia użytkownika są offline i nie można nimi sterować, więc 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ą urządzenia Assistant. Możesz 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 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 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 według użytkowników powinny być 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.

Inteligentna suszarka działa, a ktoś otwiera drzwi przed zakończeniem cyklu. Możesz wywołać metodę reportStateAndNotifications interfejsu API Google Home Graph, aby wysłać aktywne powiadomienie z parametrem errorCode:

Ten przykład pokazuje, jak wysłać aktywne powiadomienie z 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ądzeń wraz z powiadomieniami w tym samym ładunku.

Przykład 4. Powiadomienie o dalszych działaniach

W przypadku poleceń cech, które obsługują powiadomienia, możesz wysłać powiadomienie do użytkownika, gdy wystąpi błąd lub wyjątek, jeśli masz zaimplementowane smart home powiadomienia.

Użytkownik wydaje polecenie zamknięcia bramy garażowej, ale brama zacina się podczas zamykania. Możesz wysłać powiadomienie o dalszych działaniach 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
        }
      }
    }
  }
}

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

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