Wenn Geräte oder Anfragen nicht wie erwartet funktionieren, ist eine gute Fehlerbehandlung und Kommunikation für Ihre Nutzer wichtig, damit sie verstehen, was passiert ist, und möglichst auch, wie sie das Problem beheben können. Sie sollten mögliche Fehlerszenarien und die Reaktion Ihres Geräts darauf durchdenken: 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 der Nutzung 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 EXECUTE-Intent
Ein Endnutzer hat zwei intelligente Lampen in seinem Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer ein“ und Google sendet einen EXECUTE-Intent an Ihre Fulfillment-URL. Sie stellen fest, dass die Geräte des Nutzers offline und nicht steuerbar sind. Daher gibt Ihr Fulfillment 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" } ] } }
Nachdem der Google Assistant die Antwort erhalten hat, fordert er den Nutzer mit „Das Gerät ist
derzeit nicht verfügbar“ auf. Denken Sie daran, dass Sie nach dem Senden von errorCode deviceOffline in der EXECUTE-Antwort weiterhin den Offline-Status für Geräte im Statusbericht senden müssen.
Beispiel 2: Nicht blockierende Ausnahme für EXECUTE-Intent
Ein Nutzer versucht, das intelligente Schloss an seiner Eingangstür mit dem
Assistant zu verriegeln. Sie können das Schloss erfolgreich steuern, stellen aber fest, dass der Akku des Geräts fast leer ist. Daher gibt Ihr Fulfillment eine EXECUTE-Antwort mit status SUCCESS und exceptionCode lowBattery zurück.
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 der Assistant die Antwort erhalten hat, fordert er den Nutzer mit „Der Akku des Geräts ist fast leer“ auf.Assistant
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 Traits, 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 intelligenter Trockner ist in Betrieb und jemand öffnet die Tür, bevor der Zyklus beendet ist.
Sie können die Google Home Graph API
reportStateAndNotifications Methode 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 } } } } }
Nachdem der Assistant die Benachrichtigung erhalten hat, fordert er den Nutzer mit „Die Tür desGeräts ist geöffnet“ auf. Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Beispiel 4: Follow-up-Benachrichtigung
Bei Traits-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 } } } } }
Nachdem der Assistant die Benachrichtigung erhalten hat, fordert er den Nutzer mit „Das Gerät ist blockiert“ auf.Assistant Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Weitere Informationen und detaillierte errorCodes finden Sie in der
Referenzdokumentation zu Fehlern und Ausnahmen.