Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest, aby zapewnić użytkownikom skuteczne przetwarzanie błędów i komunikację, aby mogli zrozumieć, co się stało, oraz (w miarę możliwości) jak to naprawić. Zastanów się, jak urządzenie powinno reagować w różnych scenariuszach awarii: co się stanie, jeśli użytkownik przerwie wykonywane zadanie? Co się stanie, jeśli użytkownik poprosi o wykonanie czynności na urządzeniu, gdy jest ono offline? Planowanie tych problemów i pomoc użytkownikom w ich rozwiązaniu może zapobiec ich frustracji i zapewnić wyższą jakość obsługi urządzeń.
Ten przewodnik zawiera kilka przykładów odpowiedzi na intencje, które obsługują błędy. Aby sprawdzić prawidłowe wartości parametru errorCode w przypadku błędów i wyjątków, zapoznaj się z artykułem Błędy i wyjątki.
Przykład 1. Odpowiedź z błędem dla zamiaru EXECUTE
Użytkownik ma w salonie 2 inteligentne lampy. Użytkownik wydaje polecenie „włącz światła w salonie”, a Google wysyła EXECUTEintencję do Twojego adresu URL realizacji. Urządzenia użytkownika są offline i nie można nimi sterować, więc realizacja zwraca odpowiedź EXECUTE z wartościami status ERROR i errorCode deviceOffline.
Ten przykład pokazuje, jak z urządzenia świetlnego zwracać odpowiedź EXECUTE z wartością errorCode, 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 nadal musisz wysyłać stan offline urządzeń w stanie raportu po wysłaniu errorCode deviceOffline w odpowiedzi EXECUTE.
Przykład 2. Wyjątek nieblokujący dla intencji EXECUTE
Użytkownik próbuje zamknąć inteligentny zamek w drzwiach wejściowych za pomocą aplikacji Assistant. Możesz sterować blokadą, ale bateria urządzenia jest słaba, więc usługa zwraca odpowiedź EXECUTE z wartościami status, SUCCESS i exceptionCode lowBattery.
Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE z urządzeniem blokującym, korzystając z polecenia exceptionCode:
{ "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 naładowania baterii”.
Przykład 3. Aktywne powiadomienia o błędach
W niektórych przypadkach może być przydatne ostrzeżenie użytkowników przed błędem, zwłaszcza w przypadku funkcji, które użytkownicy oczekują automatycznego wykonania. W przypadku atrybutów, które obsługują aktywne powiadomienia, możesz wysyłać użytkownikom proaktywne powiadomienia, gdy wystąpi błąd, jeśli wdrożysz smart home aktywne powiadomienia.
Urządzenie pracuje w trybie inteligentnym, a ktoś otwiera drzwi przed zakończeniem cyklu.
Aby wysłać aktywne powiadomienie z użyciem interfejsu API Google Home Graph, możesz wywołać metodę reportStateAndNotifications, podając jako argument:errorCode
Ten przykład pokazuje, jak wysłać aktywne powiadomienie z urządzenia do suszenia errorCode, 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 } } } } }
Powiadomienie Assistant wysyłane do użytkownika po otrzymaniu powiadomienia o otwarciu drzwi urządzenia. W tym samym ładunku możesz wysyłać odpowiednie stany urządzenia wraz z powiadomieniami.
Przykład 4. Powiadomienie z dalszymi informacjami
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 wdrożyłeś smart home powiadomienia uzupełniające.
Użytkownik wydaje polecenie zamknięcia drzwi garażowych, ale drzwi się zacinają. Możesz wysłać kolejne powiadomienie 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 } } } } }
Powiadomienie Assistant wyświetla użytkownikowi komunikat „Urządzenie jest zablokowane”. Stany urządzenia można wysyłać razem z powiadomieniami w ramach tego samego ładunku danych.
Więcej informacji i szczegółowe informacje o errorCodes znajdziesz w dokumentacji Błędy i wyjątki.