Jeśli urządzenia lub żądania nie działają zgodnie z oczekiwaniami, zadbaj o poprawną obsługę błędów i komunikację z użytkownikami, aby wiedzieli, co się stało i jak można je naprawić. Pamiętaj o możliwych scenariuszach awarii i o tym, jak zareaguje urządzenie – co zrobić, jeśli użytkownik zakłóci działanie zadania? Co się stanie, gdy użytkownik poprosi o działanie z urządzenia w trybie offline? Planowanie tych problemów i pomaganie użytkownikom w ich regenerowaniu może uniknąć frustracji użytkowników i zwiększać jakość Twoich urządzeń.
Ten przewodnik zawiera kilka przykładów odpowiedzi na zamiar, które obsługują błędy. Prawidłowe wartości errorCode dla błędów i wyjątków znajdziesz w sekcji Błędy i wyjątki.
Przykład 1. Odpowiedź błędu dotycząca intencji EXECUTE
Użytkownik ma 2 inteligentne żarówki 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ć, dlatego w Twojej realizacji pojawi się odpowiedź EXECUTE z danymi status ERROR i errorCode deviceOffline.
Ten przykład pokazuje, jak zwrócić odpowiedź EXECUTE za pomocą 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"
}
]
}
}
Po otrzymaniu odpowiedzi Google Assistant wyświetli użytkownikowi komunikat „Urządzenie jest teraz niedostępne”. Pamiętaj, że po wysłaniu errorCode deviceOffline w odpowiedzi EXECUTE nadal musisz wysłać stan offline na urządzenia w stanie raportu.
Przykład 2. Nieblokujący wyjątek dotyczący intencji EXECUTE
Użytkownik próbuje zablokować funkcję Smart Lock przy drzwiach wejściowych, używając urządzenia z urządzeniem Assistant. Możesz którymś zarządzać zamkiem, ale zauważysz, że bateria w urządzeniu jest słaba, więc w trakcie realizacji zobaczysz odpowiedź EXECUTE z status SUCCESS i exceptionCode lowBattery.
Ten przykład pokazuje, jak wysłać odpowiedź EXECUTE za pomocą 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 Assistant wyświetli komunikat „użytkownik urządzenia ma niski poziom baterii”.
Przykład 3. Aktywne powiadomienia o błędach
W niektórych przypadkach warto poinformować użytkowników o błędach, zwłaszcza w przypadku funkcji, które użytkownicy powinni wykonać automatycznie. W przypadku cech, które obsługują powiadomienia bez pytania, możesz powiadomić użytkownika o błędach, jeśli masz wdrożone smart home aktywne powiadomienia.
Inteligentna suszarka jest uruchomiona, a ktoś otwiera drzwi przed końcem cyklu.
Możesz wywołać metodę Google Home Graph APIreportStateAndNotifications, aby wysłać aktywne powiadomienie za pomocą errorCode:
Ten przykład pokazuje, jak wysłać aktywne powiadomienie z errorCode przy użyciu 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 komunikat z informacją „otwarte drzwi urządzenia”. Wraz z powiadomieniami możesz wysłać odpowiednie stany urządzenia.
Przykład 4. Dalsze powiadomienie
W przypadku poleceń cech, które obsługują dalsze powiadomienia, możesz wysłać użytkownikowi powiadomienie po wystąpieniu błędu lub wyjątku, jeśli masz zaimplementowane smart home powiadomienia.
Użytkownik wydaje polecenie zamknięcia drzwi garażowych, ale drzwi się zacięły podczas zamykania. Możesz wysłać kolejne powiadomienie na 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 komunikat z informacją, że urządzenie się zacięło. Możesz wysyłać odpowiadające im stany urządzeń z powiadomieniami w tym samym ładunku.
Więcej informacji oraz szczegółowe informacje na temat obiektu errorCodes znajdziesz w dokumentacji Błędy i wyjątki.