Gdy urządzenia lub żądania nie działają zgodnie z oczekiwaniami, ważne jest, aby użytkownicy byli w stanie odpowiednio obsługiwać błędy i komunikować się ze sobą. Dzięki temu będą oni wiedzieć, co się stało, i jeśli to możliwe, jak rozwiązać ten problem. Przemyśl możliwe scenariusze awarii i przemyśl, jak zareaguje urządzenie: „Co się stanie, jeśli użytkownik przerwie zadanie? Co się stanie, gdy użytkownik poprosi o działanie z urządzenia, gdy jest offline? Zaplanowanie takich problemów i pomoc w ich rozwiązaniu pozwala uniknąć frustracji użytkowników i poprawić komfort korzystania z urządzeń.
Ten przewodnik zawiera kilka przykładów odpowiedzi intencji, które obsługują błędy. Zajrzyj do sekcji Błędy i wyjątki, aby sprawdzić prawidłowe wartości errorCode pod kątem błędów i wyjątków.
Przykład 1: odpowiedź o błędzie w przypadku intencji EXECUTE
Użytkownik ma w salonie 2 inteligentne żarówki. Użytkownik wykonuje polecenie „włącz światło w salonie”, a Google wysyła zamiar EXECUTE na Twój adres URL realizacji zamówień. Okazuje się, że urządzenia użytkownika są offline i nie można ich kontrolować, więc realizacja zwraca odpowiedź EXECUTE z wartością status ERROR i errorCode deviceOffline.
Ten przykład pokazuje, jak w opisany wcześniej sposób zwrócić odpowiedź EXECUTE z elementem errorCode z urządzenia lekkiego:
{
"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świetli użytkownikowi komunikat „urządzenie jest teraz niedostępne”. Pamiętaj, że nadal musisz wysyłać informacje o stanie offline w przypadku 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 na drzwiach wejściowych, używając urządzenia z funkcją Assistant. Możesz kontrolować blokadę urządzenia, ale okazuje się, że bateria w urządzeniu jest słaba, więc realizacja zwraca odpowiedź EXECUTE z wartościami status SUCCESS i exceptionCode lowBattery.
Ten przykład pokazuje, jak wysłać z urządzenia blokady odpowiedź EXECUTE z elementem exceptionCode 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"
}
}]
}
}
Po otrzymaniu odpowiedzi Assistant wyświetli użytkownikowi komunikat „urządzenie ma niski poziom baterii”.
Przykład 3. Aktywne powiadomienia o błędach
W niektórych przypadkach warto ostrzec użytkowników o błędzie, zwłaszcza w przypadku funkcji, które użytkownicy spodziewają się wykonać automatycznie. W przypadku cech, które obsługują aktywne powiadomienia, możesz aktywnie powiadomić użytkownika o błędzie, jeśli masz zaimplementowane smart home powiadomienia proaktywne.
Inteligentna suszarka jest włączona, a ktoś otwiera drzwi przed zakończeniem cyklu.
Możesz wywołać metodę reportStateAndNotifications interfejsu Google Home Graph API, aby wysłać aktywne powiadomienie z errorCode:
Ten przykład pokazuje, jak wysłać z suszarki aktywne powiadomienie za pomocą polecenia errorCode w sposób opisany 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 „Drzwi urządzenia jest otwarte”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń razem z powiadomieniami.
Przykład 4. Dalsze powiadomienie
W przypadku poleceń cechy, które obsługują kolejne powiadomienia, możesz wysłać użytkownikowi powiadomienie o błędzie lub wyjątku, jeśli masz zaimplementowane smart home powiadomienia o dalszych czynnościach.
Użytkownik wydaje polecenie zamknięcia bramy garażowej, ale podczas zamykania się zacinają. Możesz wysłać kolejne powiadomienie za pomocą urządzenia 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świetli użytkownikowi komunikat „urządzenie jest zacięte”. W tym samym ładunku możesz wysyłać odpowiednie stany urządzeń z powiadomieniami.
Więcej informacji i szczegółowe informacje na temat errorCodes znajdziesz w dokumentacji dotyczącej błędów i wyjątków.