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 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 Sie diese Probleme berücksichtigen und Nutzern helfen, sie zu beheben, können Sie Frustrationen vermeiden und die Nutzerfreundlichkeit 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 den Intent EXECUTE
Ein Endnutzer hat zwei intelligente Lampen in seinem Wohnzimmer installiert. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer an“ und Google sendet eine EXECUTEIntent 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"
}
]
}
}
Der 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 EXECUTE-Intent
Ein Nutzer versucht, das intelligente Schloss an seiner Haustür 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"
}
}]
}
}
Die Assistant fordert den Nutzer nach Erhalt der Antwort auf, den Akku des Geräts zu laden.
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 einer 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 Attributbefehlen, 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 seines Garagentors, aber das Tor bleibt beim Schließen stecken. 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
}
}
}
}
}
Der Assistant fordert den Nutzer nach Erhalt der Benachrichtigung auf, das Gerät zu entsperren. 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.