Fehler und Ausnahmen verarbeiten

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 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"
      }
    ]
  }
}

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.