Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest zapewnienie użytkownikom prawidłowej obsługi błędów i komunikacja, tak aby rozumieli, co się stało i jak można to naprawić. Zastanów się, jakie są możliwe scenariusze awarii, i jak będzie reagować urządzenie: co się stanie, jeśli użytkownik przerwie trwające zadanie? Co się stanie, jeśli użytkownik poprosi o wykonanie działania z urządzenia, gdy urządzenie jest offline? Planowanie tych problemów i pomaganie użytkownikom w odzyskaniu ich frustracji pozwala uniknąć frustracji użytkowników i sprawia, że Twoje urządzenia działają lepiej.
Ten przewodnik zawiera przykłady odpowiedzi na zamiary, które obsługują błędy. Prawidłowe wartości errorCode
błędów i wyjątków znajdziesz w sekcji Błędy i wyjątki.
Przykład 1. Odpowiedź błędu w przypadku intencji EXECUTE
Użytkownik ma 2 inteligentne światła zainstalowane w salonie. Użytkownik wydaje polecenie „Włącz światło w salonie”, a Google wysyła intencję EXECUTE
do Twojego adresu URL realizacji. Okazało się, że urządzenia użytkownika są offline i których nie można kontrolować, więc Twoja realizacja zwraca odpowiedź EXECUTE
z tagami status
ERROR
i errorCode
deviceOffline
.
Ten przykład pokazuje, jak zwrócić odpowiedź EXECUTE
z tagiem 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
will prompt the user with "the device are
not available right now" after receiving the response. Remember that you still
need to send offline state for devices in report state after sending
errorCode
deviceOffline
in EXECUTE
response.
Przykład 2: wyjątek nieblokujący dla intencji EXECUTE
Użytkownik próbuje zablokować Smart Lock przy drzwiach wejściowych, używając urządzenia z systemem Assistant. Możesz skutecznie zablokować zamek, ale okaże się, że bateria urządzenia jest słaba, przez co realizacja będzie zwracać odpowiedź EXECUTE
z status
SUCCESS
i exceptionCode
lowBattery
.
Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE
z tagiem 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 użytkownik Assistant wyświetli komunikat z komunikatem „Urządzenie ma niski poziom baterii”.
Przykład 3. Aktywne powiadomienia o błędach
W niektórych przypadkach może być przydatne ostrzeżenie użytkowników o błędach, zwłaszcza w przypadku funkcji, które użytkownicy mogą ukończyć automatycznie. W przypadku cech, które obsługują powiadomienia aktywne, możesz powiadomić użytkownika o ewentualnym błędzie, jeśli zastosujesz go.smart home proactive notifications.
Inteligentna suszarka działa, a ktoś otwiera drzwi przed zakończeniem cyklu.
Możesz zadzwonić pod numer
Google Home Graph
API
reportStateAndNotifications
method to send a proactive notification with an
errorCode
:
Ten przykład pokazuje, jak wysłać aktywne powiadomienie z urządzeniem 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świetli użytkownikowi komunikat „otwarte drzwi urządzenia”. Odpowiednie stany urządzenia możesz wysłać wraz z powiadomieniami w ramach tego samego ładunku.
Przykład 4. Powiadomienie
W przypadku poleceń cech, które obsługują dalsze powiadomienia, możesz wysłać użytkownikowi powiadomienie uzupełniające w przypadku wystąpienia błędu lub wyjątku, jeśli wdrożysz smart home dalsze powiadomienia.
Użytkownik wydaje polecenie zamknięcia drzwi do garażu, ale drzwi się zacięły podczas zamykania. Możesz wysłać dalsze powiadomienie 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 } } } } }
Assistant otrzyma powiadomienie z komunikatem „urządzenie się zaciąło”. Za pomocą tego samego ładunku możesz też wysyłać odpowiednie stany urządzenia z powiadomieniami.
Więcej informacji i szczegółowe informacje na temat obiektu errorCodes
znajdziesz w dokumentacji referencyjnej dotyczącej błędów i wyjątków.