Wenn Geräte oder Anfragen nicht wie erwartet funktionieren, ist es wichtig, eine gute Fehlerbehandlung und Kommunikation für deine Nutzer bereitzustellen, damit sie verstehen, was passiert ist, und nach Möglichkeit, wie sie das Problem beheben können. Denke über mögliche Fehlerszenarien nach und wie dein Gerät darauf reagieren sollte: Was passiert, wenn ein Nutzer eine laufende Aufgabe unterbricht? Was passiert, wenn ein Nutzer eine Aktion von einem Gerät anfordert, während es offline ist? Wenn du diese Probleme einplanst und deinen Nutzern hilfst, sie zu beheben, kannst du Frustration vermeiden und die Qualität deiner Geräte verbessern.
In diesem Leitfaden finden Sie einige Beispiele für Intent-Antworten, die Fehler behandeln. Unter Fehler und Ausnahmen finden Sie die gültigen errorCode-Werte für Fehler und Ausnahmen.
Beispiel 1: Fehlerantwort für die Intent EXECUTE
Ein Endnutzer hat zwei smarte Lampen in seinem Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer ein“ und Google sendet einen EXECUTE-Intent an deine Ausführungs-URL. Du hast festgestellt, dass die Geräte des Nutzers offline sind und nicht gesteuert werden können. Daher gibt deine Ausführung eine EXECUTE-Antwort mit status ERROR und errorCode deviceOffline zurück.
In diesem Beispiel wird gezeigt, wie Sie eine EXECUTE-Antwort mit einem errorCode von einem Lichtgerät zurückgeben, wie oben beschrieben:
{ "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 fordert den Nutzer nach Erhalt der Antwort mit „Gerät ist derzeit nicht verfügbar“ auf. Denke daran, dass du nach dem Senden von errorCode deviceOffline in der EXECUTE-Antwort weiterhin den Offlinestatus für Geräte im Berichtsstatus senden musst.
Beispiel 2: Nicht blockierende Ausnahme für die Absicht EXECUTE
Ein Nutzer versucht, das smarte Schloss an seiner Haustür mit Assistant zu verriegeln. Du kannst das Schloss erfolgreich steuern, stellst aber fest, dass der Akkustand des Geräts niedrig ist. Daher gibt deine Ausführung eine EXECUTE-Antwort mit status SUCCESS und exceptionCode lowBattery zurück.
In diesem Beispiel wird gezeigt, wie eine EXECUTE-Antwort mit einem exceptionCode von einem Schloss gesendet wird, wie oben beschrieben:
{ "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" } }] } }
Assistant fordert den Nutzer nach Erhalt der Antwort mit „Der Akkustand von Gerät ist niedrig“ auf.
Beispiel 3: Proaktive Fehlerbenachrichtigungen
In einigen Fällen kann es hilfreich sein, Nutzer auf einen Fehler hinzuweisen, insbesondere bei Funktionen, die Nutzer automatisch ausführen möchten. Bei Eigenschaften, die proaktive Benachrichtigungen unterstützen, kannst du den Nutzer proaktiv benachrichtigen, wenn ein Fehler auftritt, sofern du smart home proaktive Benachrichtigungen implementiert hast.
Ein smarter Trockner läuft und jemand öffnet die Tür, bevor der Trocknungsvorgang abgeschlossen ist.
Du kannst die reportStateAndNotifications-Methode der Google Home Graph API aufrufen, um eine proaktive Benachrichtigung mit einem errorCode zu senden:
In diesem Beispiel wird gezeigt, wie Sie eine proaktive Benachrichtigung mit einem errorCode von einem Trockner senden, wie oben beschrieben:
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 } } } } }
Assistant fordert den Nutzer nach Erhalt der Benachrichtigung mit „Die Tür von Gerät ist geöffnet“ auf. Du kannst die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Beispiel 4: Erinnerungsbenachrichtigung
Bei Befehlen für Eigenschaften, die Folgenachrichten unterstützen, kannst du dem Nutzer eine Folgenachricht senden, wenn ein Fehler oder eine Ausnahme auftritt, sofern du smart home Folgenachrichten implementiert hast.
Ein Nutzer gibt einen Befehl zum Schließen des Garagentors, aber das Tor klemmt beim Schließen. Sie können eine Folgenachricht mit einem errorCode senden:
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 fordert den Nutzer nach Erhalt der Benachrichtigung mit „Das Gerät ist blockiert“ auf. Du kannst die entsprechenden Gerätestatus mit Benachrichtigungen in derselben Nutzlast senden.
Weitere Informationen und detaillierte errorCodes finden Sie in der Referenzdokumentation zu Fehlern und Ausnahmen.