Wenn Geräte oder Anfragen nicht wie erwartet funktionieren, ist es wichtig, eine gute Fehlerbehandlung und Kommunikation für Ihre Nutzer bereitzustellen, damit sie verstehen, was passiert ist und nach Möglichkeit, wie sie das Problem beheben können. Überlegen Sie sich mögliche Fehlerszenarien und wie Ihr Gerät darauf 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 planen und den Nutzern bei der Wiederherstellung helfen, können Sie Frustration vermeiden und die Qualität Ihrer Geräte verbessern.
Dieser Leitfaden enthält einige Beispiele für Intent-Antworten, die mit Fehlern umgehen. Unter Fehler und Ausnahmen finden Sie Informationen zu den gültigen errorCode
-Werten für Fehler und Ausnahmen.
Beispiel 1: Fehlerantwort für Intent EXECUTE
Ein Endnutzer hat zwei intelligente Lampen im Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer an“ und Google sendet eine EXECUTE
Intent an Ihre Ausführungs-URL. Sie haben festgestellt, dass die Geräte des Nutzers offline und nicht steuerbar sind. Daher gibt Ihre Auftragsausführung eine EXECUTE
-Antwort mit status
ERROR
und errorCode
deviceOffline
zurück.
In diesem Beispiel wird gezeigt, wie eine EXECUTE
-Antwort mit einer errorCode
von einem Leuchtmittel 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 nach Erhalt der Antwort auf, „das Gerät zu verwenden, das derzeit nicht verfügbar ist“. Denken Sie daran, dass Sie den Offlinestatus für Geräte im Berichtsstatus senden müssen, nachdem Sie errorCode
deviceOffline
in der EXECUTE
-Antwort gesendet haben.
Beispiel 2: Nicht blockierende Ausnahme für den Intent EXECUTE
Ein Nutzer versucht, sein intelligentes Schloss an der Haustür mit einem Gerät mit Assistant zu verriegeln. Sie können das Schloss zwar steuern, aber der Akku des Geräts ist schwach. Daher gibt die Auslieferung eine EXECUTE
-Antwort mit status
SUCCESS
und exceptionCode
lowBattery
zurück.
In diesem Beispiel wird gezeigt, wie Sie wie oben beschrieben eine EXECUTE
-Antwort mit einer exceptionCode
von einem Schlossgerät senden:
{ "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 empfangen wurde, wird der Nutzer von Assistant mit der Meldung „Der Akku des Geräts ist schwach“ aufgefordert.
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. 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 intelligenter Trockner läuft und jemand öffnet die Tür, bevor der Zyklus beendet ist.
Sie können die Google Home Graph API-Methode reportStateAndNotifications
aufrufen, um eine proaktive Benachrichtigung mit einer errorCode
zu senden:
In diesem Beispiel wird gezeigt, wie Sie wie oben beschrieben eine proaktive Benachrichtigung mit einem errorCode
von einem Trockner 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": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
Die Assistant fordert den Nutzer nach Erhalt der Benachrichtigung auf, die Tür des Geräts zu öffnen. Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Beispiel 4: Folgebenachrichtigung
Bei Befehlen für Merkmale, die Folgebenachrichtigungen unterstützen, können Sie dem Nutzer eine Folgebenachrichtigung senden, wenn ein Fehler oder eine Ausnahme auftritt, sofern Sie smart home Folgebenachrichtigungen implementiert haben.
Ein Nutzer gibt den Befehl zum Schließen des Garagentors, aber das Tor klemmt, während es geschlossen wird. Sie können eine weitere 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 } } } } }
Die Assistant zeigt dem Nutzer nach Erhalt der Benachrichtigung an, dass das Gerät blockiert ist. Sie können die entsprechenden Gerätestatus mit Benachrichtigungen in derselben Nutzlast senden.
Weitere Informationen und eine detaillierte errorCodes
finden Sie in der Referenzdokumentation zu Fehlern und Ausnahmen.