Wenn Geräte oder Anfragen nicht wie erwartet funktionieren, ist es wichtig, den Nutzern eine gute Fehlerbehandlung und Kommunikation zu bieten, damit sie nachvollziehen können, was passiert ist und wie dies behoben werden kann. Denke über mögliche Fehlerszenarien und die Reaktionen deines Geräts nach: Was passiert, wenn ein Nutzer eine laufende Aufgabe unterbricht? Was ist, wenn ein Nutzer eine Aktion von einem Gerät anfordert, während es offline ist? Wenn Sie diese Probleme planen und Ihren Nutzern helfen, sie zu wiederherstellen, können Sie Frustration vermeiden und die Nutzerfreundlichkeit Ihrer Geräte verbessern.
In diesem Leitfaden finden Sie einige Beispiele für Intent-Antworten, die Fehler beheben. Die gültigen errorCode-Werte auf Fehler und Ausnahmen finden Sie unter Fehler und Ausnahmen.
Beispiel 1: Fehlerantwort für EXECUTE-Intent
Ein Endnutzer hat zwei intelligente Lampen und wird im Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte die Beleuchtung im Wohnzimmer“ aus und Google hat einen EXECUTE-Intent an die Auftragsausführungs-URL gesendet. Sie haben festgestellt, dass die Geräte des Nutzers offline und nicht steuerbar sind. Ihre Auftragsausführung gibt also eine EXECUTE-Antwort mit status ERROR und errorCode deviceOffline zurück.
Dieses Beispiel zeigt, wie eine EXECUTE-Antwort mit einem errorCode von einem hellen Gerät zurückgegeben wird, wie zuvor 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 ruft nach der Antwort die Meldung „device ist derzeit nicht verfügbar“ auf. Denken Sie daran, dass Sie immer noch 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 EXECUTE-Intent
Ein Nutzer versucht, sein Smart Lock vor der Tür mithilfe eines Geräts mit Assistant zu verriegeln. Sie können die Sperre verwalten, aber der Geräteakku ist niedrig. Ihre Auftragsausführung gibt also eine EXECUTE-Antwort mit status SUCCESS und exceptionCode lowBattery zurück.
Dieses Beispiel zeigt, wie eine EXECUTE-Antwort mit einem exceptionCode von einem gesperrten Gerät gesendet wird:
{
"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"
}
}]
}
}
Bei Assistant wird der Nutzer mit der Meldung „device hat schwachen Akku“ aufgefordert, nachdem er die Antwort erhalten hat.
Beispiel 3: Proaktive Fehlerbenachrichtigungen
In einigen Fällen kann es hilfreich sein, Nutzer auf einen Fehler hinzuweisen, vor allem bei Funktionen, die Nutzer automatisch ausführen. Bei Merkmalen, die proaktive Benachrichtigungen unterstützen, kannst du den Nutzer proaktiv benachrichtigen, wenn ein Fehler auftritt, wenn du smart home proaktive Benachrichtigungen implementiert hast.
Ein intelligenter Trockner wird ausgeführt und jemand öffnet die Tür, bevor der Zyklus abgeschlossen ist.
Sie können die Methode reportStateAndNotifications der Google Home Graph API aufrufen, um mit einer errorCode eine proaktive Benachrichtigung zu senden:
In diesem Beispiel wird gezeigt, wie Sie wie oben beschrieben mit einem errorCode-Trocknergerät eine proaktive Benachrichtigung 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
}
}
}
}
}
Nach dem Erhalt der Benachrichtigung fordert Assistant Nutzer dazu auf, „die Tür Gerät zu öffnen“. Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.
Beispiel 4: Follow-up-Benachrichtigung
Für Trait-Befehle, die Folgebenachrichtigungen unterstützen, können Sie dem Nutzer eine Folgebenachrichtigung senden, während ein Fehler oder eine Ausnahme auftritt, wenn Sie smart home-Folgebenachrichtigungen implementiert haben.
Ein Nutzer gibt einen Befehl zum Schließen des Garagentors aus, aber die Tür klemmt beim Schließen fest. Du kannst eine Folgebenachrichtigung 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 benachrichtigt den Nutzer mit „Das Gerät ist gestört“, nachdem die Benachrichtigung empfangen wurde. Sie können die entsprechenden Gerätestatus mit Benachrichtigungen in derselben Nutzlast senden.
Weitere Informationen und ausführliche Informationen zu errorCodes finden Sie in der Referenzdokumentation zu Fehlern und Ausnahmen.