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 zu bieten, damit sie verstehen, was passiert ist, und wann immer möglich, wie Sie es beheben können. Denken Sie unbedingt über mögliche Fehlerszenarien nach und überlegen Sie, wie Ihr Gerät reagieren wird. 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 du diese Probleme einplanst und den Nutzern dabei hilfst, sie wieder zu retten, vermeidest du Frustration bei den Nutzern und profitierst von einer besseren Nutzung deiner Geräte.

Dieser Leitfaden enthält einige Beispiele für Intent-Antworten, die Fehler verarbeiten. Unter Fehler und Ausnahmen finden Sie die gültigen errorCode-Werte auf Fehler und Ausnahmen.

Beispiel 1: Fehlerantwort für den Intent EXECUTE

Ein Endnutzer hat zwei intelligente Lampen, die im Wohnzimmer installiert sind. Der Nutzer gibt den Befehl „Schalte das Licht im Wohnzimmer ein“ 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. Daher gibt die Auftragsausführung 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 Light-Gerät wie oben beschrieben zurückgeben:

{
  "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 fordert den Nutzer nach Erhalt der Antwort mit der Meldung „Das Gerät sind im Moment nicht verfügbar“ an. Denken Sie daran, dass für Geräte im Berichtsstatus weiterhin der Offlinestatus gesendet werden muss, nachdem errorCode deviceOffline in der EXECUTE-Antwort gesendet wurde.

Beispiel 2: Nicht blockierende Ausnahme für den Intent EXECUTE

Ein Nutzer versucht, sein Smart Lock an der Haustür mit einem Gerät mit Assistant zu verriegeln. Sie können die Sperre erfolgreich steuern, aber Sie stellen fest, dass der Akku des Geräts schwach ist. Daher gibt die Auftragsausführung 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 Sperrgerät wie oben beschrieben 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"
      }
    }]
  }
}

Nach Erhalt der Antwort von Assistant fordert der Nutzer die Meldung „Das Gerät hat einen niedrigen Akkustand auf.“

Beispiel 3: Proaktive Fehlerbenachrichtigungen

In einigen Fällen kann es hilfreich sein, Nutzer über einen Fehler zu informieren, insbesondere bei Funktionen, die die Nutzer automatisch ausführen sollen. Bei Traits, die proaktive Benachrichtigungen unterstützen, können Sie den Nutzer proaktiv benachrichtigen, während ein Fehler auftritt. Dazu müssen Sie proaktive smart home-Benachrichtigungen implementiert haben.

Ein intelligenter Trockner läuft und jemand öffnet die Tür, bevor der Waschgang beendet ist. Sie können die reportStateAndNotifications-Methode der Google Home Graph API aufrufen, um eine proaktive Benachrichtigung mit einem errorCode zu senden:

Dieses Beispiel zeigt, wie eine proaktive Benachrichtigung mit einem errorCode von einem Trocknergerät gesendet wird, 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
        }
      }
    }
  }
}

Assistant fordert den Nutzer nach Erhalt der Benachrichtigung mit der Meldung „Die Gerätetür ist geöffnet“ auf. Sie können die entsprechenden Gerätestatus zusammen mit Benachrichtigungen in derselben Nutzlast senden.

Beispiel 4: Folgebenachrichtigung

Für Traits-Befehle, die Folgebenachrichtigungen unterstützen, können Sie eine Folgebenachrichtigung an den Nutzer senden, während ein Fehler oder eine Ausnahme auftritt. Dazu müssen Sie Folgebenachrichtigungen smart home implementiert haben.

Ein Nutzer gibt einen Befehl zum Schließen des Garagentors aus, aber das Tor klemmt beim Schließen. 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 fordert den Nutzer nach Erhalt der Benachrichtigung mit der Meldung „Das Gerät ist klemmt“ auf. 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.