Wenn Geräte oder Anfragen nicht wie erwartet funktionieren, ist es wichtig, dass Sie Ihren Nutzern eine gute Fehlerbehandlung und Kommunikation bieten, damit sie verstehen, was passiert ist und, wenn möglich, wie sie das Problem beheben können. Denken Sie über mögliche Fehlerszenarien nach und überlegen Sie, wie Ihr Gerät reagieren soll: 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 Sie diese Probleme einplanen und Ihren Nutzern helfen, sie zu beheben, können Sie Frustrationen vermeiden und die Qualität Ihrer Geräte verbessern.
In dieser Anleitung 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 den Intent EXECUTE
Ein Endnutzer hat zwei smarte Glühbirnen in seinem Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer an“ und Google sendet einen EXECUTE-Intent an deine Fulfillment-URL. Sie haben festgestellt, dass die Geräte des Nutzers offline und nicht steuerbar sind. Ihre Auftragsausführung gibt daher eine EXECUTE-Antwort mit status ERROR und errorCode deviceOffline zurück.
In diesem Beispiel wird gezeigt, wie eine EXECUTE-Antwort mit einem errorCode von einem Lichtgerät zurückgegeben wird, 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" } ] } }
Die Google Assistant fordert den Nutzer mit „Das Gerät ist derzeit nicht verfügbar“ auf, nachdem die Antwort eingegangen ist. Denken Sie daran, dass Sie nach dem Senden von errorCode deviceOffline in der EXECUTE-Antwort weiterhin den Offlinestatus für Geräte im Berichtsstatus senden müssen.
Beispiel 2: Nicht blockierende Ausnahme für die Intention EXECUTE
Ein Nutzer versucht, das Smart-Lock an seiner Eingangstür mit Assistant zu verriegeln. Sie können das Schloss erfolgreich steuern, aber der Akku des Geräts ist fast leer. Daher wird in Ihrer Ausführung eine EXECUTE-Antwort mit status SUCCESS und exceptionCode lowBattery zurückgegeben.
In diesem Beispiel wird gezeigt, wie Sie eine EXECUTE-Antwort mit einem exceptionCode von einem Schlossgerät senden, 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" } }] } }
Nachdem die Antwort eingegangen ist, wird der Nutzer mit Assistant aufgefordert, das Gerät aufzuladen, da der Akku schwach ist.
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 lassen möchten. Bei Merkmalen, die proaktive Benachrichtigungen unterstützen, können Sie den Nutzer proaktiv benachrichtigen, wenn ein Fehler auftritt, sofern Sie smart home proaktive Benachrichtigungen implementiert haben.
Ein Smart-Trockner läuft und jemand öffnet die Tür, bevor der Zyklus abgeschlossen ist.
Sie können die Google Home Graph API-Methode reportStateAndNotifications 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 Trocknergerät 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 } } } } }
Die Assistant fordert den Nutzer mit „Die Tür des Geräts wurde geöffnet“ auf, nachdem er die Benachrichtigung erhalten hat. Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Beispiel 4: Follow-up-Benachrichtigung
Bei Trait-Befehlen, die Follow-up-Benachrichtigungen unterstützen, können Sie dem Nutzer eine Follow-up-Benachrichtigung senden, wenn ein Fehler oder eine Ausnahme auftritt, sofern Sie smart home Follow-up-Benachrichtigungen implementiert haben.
Ein Nutzer gibt einen Befehl zum Schließen des Garagentors, aber das Tor klemmt beim Schließen. Sie können eine Follow-up-Benachrichtigung 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 } } } } }
Der Assistant fordert den Nutzer mit „Das Gerät ist blockiert“ auf, nachdem er die Benachrichtigung erhalten hat. Sie können die entsprechenden Gerätestatus mit Benachrichtigungen in derselben Nutzlast senden.
Weitere Informationen und detaillierte errorCodes finden Sie in der Referenzdokumentation zu Fehlern und Ausnahmen.