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

Jeśli urządzenia lub żądania nie działają zgodnie z oczekiwaniami, należy podać obsługi błędów i komunikacji z użytkownikami, tak aby wiedzieli, co oraz jak w miarę możliwości rozwiązać ten problem. Dobrze się zastanów możliwych scenariuszy awarii i tego, jak zareaguje urządzenie: co zrobić, jeśli użytkownik przerywa wykonywane zadanie? Co, jeśli użytkownik poprosi o działanie z urządzenia gdy jest offline? Planowanie rozwiązywania problemów i pomaganie użytkownikom w odzyskiwaniu konta mogą uniknąć frustracji użytkowników i zapewnić lepsze wrażenia na Twoich urządzeniach.

W tym przewodniku znajdziesz kilka przykładów odpowiedzi intencji, które obsługują błędy. Zobacz Błędy i wyjątki sprawdź prawidłowe wartości errorCode dla błędów i wyjątków.

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

Użytkownik ma 2 inteligentne światła zamontowane w salonie. Użytkownik Wydaje polecenie „włącz światło w salonie” i wysłaliśmy EXECUTE do adresu URL realizacji. Okazało się, że urządzenia użytkownika są offline i nie da się jej skontrolować, więc realizacja zwraca odpowiedź EXECUTE z: status ERROR i errorCode deviceOffline.

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

Google Assistant wyświetli użytkownikowi pytanie „urządzenie jest aktualnie niedostępne” po otrzymaniu odpowiedzi. Pamiętaj, że trzeba wysyłać informacje o stanie offline w przypadku urządzeń w stanie raportowania po wysłaniu errorCode deviceOffline w EXECUTE odpowiedzi.

Przykład 2. Nieblokujący wyjątek dla intencji EXECUTE

Użytkownik próbuje zamknąć inteligentny zamek przy drzwiach wejściowych przy użyciu urządzenia z Assistant Możesz sterować jego blokadą, ale masz słabą baterię w urządzeniu, więc realizacja zamówienia zwraca EXECUTE odpowiedź z wartością status SUCCESS i exceptionCode lowBattery.

Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE ze znakiem exceptionCode na zablokowanym urządzeniu w sposób opisany 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"
      }
    }]
  }
}

Assistant wyświetli użytkownikowi komunikat „urządzenie ma niski poziom naładowania bateria” po otrzymaniu odpowiedzi.

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

W niektórych przypadkach warto powiadomić użytkowników o błędzie, szczególnie funkcji, które użytkownicy chcą wykonywać automatycznie. Jeśli chodzi o cechy, obsługuje aktywne powiadomienia, możesz powiadamiać użytkownika, gdy występuje błąd, jeśli zaimplementowano tag smart home aktywne powiadomienia.

Inteligentna suszarka jest uruchomiona, a ktoś otwiera drzwi przed zakończeniem cyklu. Możesz wywołać interfejs API Google Home Graph reportStateAndNotifications, aby wysłać aktywne powiadomienie z 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
        }
      }
    }
  }
}

Urządzenie Assistant wyświetli użytkownikowi pytanie „Urządzenie device to otwarta” po otrzymaniu powiadomienia. Możesz wysłać odpowiednią stany urządzeń i powiadomienia w ramach tego samego ładunku.

Przykład 4. Powiadomienie o dalszych czynnościach

W przypadku poleceń dotyczących cech, które obsługują dodatkowe powiadomienia, możesz wysłać powiadomienie dla użytkownika w razie wystąpienia błędu lub wyjątku, jeśli: wdrożono smart home dalsze powiadomienia.

Użytkownik wydaje polecenie zamknięcia bramy garażowej, ale w drzwiach coś się zacięło podczas zamykania. Możesz wysłać dodatkowe powiadomienie, używając 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
        }
      }
    }
  }
}

Assistant wyświetli użytkownikowi pytanie „urządzenie to zacięty” po otrzymaniu powiadomienia. Możesz wysłać odpowiednią na urządzeniach z powiadomieniami w ramach tego samego ładunku.

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