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ń.
W tym przewodniku znajdziesz 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 2 inteligentne lampy zainstalowane w salonie. Użytkownik wydaje polecenie „włącz światła w salonie”, a Google wysyła do Twojego adresu URL realizacji EXECUTEintencję. 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 wyświetla użytkownikowi komunikat „Drzwi urządzenia są otwarte”. W ramach tego samego ł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ś/wdroczyłaś 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.