Fehler und Ausnahmen

In diesem Dokument werden die offiziell unterstützten Fehler und Ausnahmen für Smart-Home-Geräte aufgeführt. Verwende diese Fehler- und Ausnahmecodes in der Intent-Antwort oder in Benachrichtigungen, falls du sie implementiert hast, damit Google Assistant Endnutzer auf Probleme im Zusammenhang mit einem bestimmten Befehl oder Gerätestatus hinweist. Wenn die Antwort eine falsche Formatierung oder errorCode enthält, gibt Google Assistant eine allgemeine Fehlermeldung aus, z. B. „Gerät ist derzeit nicht verfügbar“.

Fehler

Du solltest einen Fehlercode zurückgeben, wenn ein Problem dazu führt, dass eine Ausführungs- oder Abfrageanfrage fehlschlägt. Wenn beispielsweise ein Türschloss klemmt und nicht ver- oder entriegelt werden kann, sollte der Nutzer eine Fehlermeldung zu diesem Zustand erhalten.

Fehlercodes können auf Geräteebene oder auf globaler Ebene angehängt werden. Wenn ein Nutzer beispielsweise viele Lampen von einem Anbieter hat, die über einen Hub gesteuert werden, und der Nutzer alle Lampen ausschalten möchte, kann der Anbieter einen Fehler auf Geräteebene zurückgeben, wenn eine einzelne Lampe offline ist, oder einen Fehler auf globaler Ebene, wenn der gesamte Hub offline ist und keine Lampen gesteuert werden können. Wenn alle Geräte offline sind, gibt es keinen Unterschied zwischen Fehlern auf globaler Ebene und Fehlern auf Geräteebene.

Zusammenfassung:

• Fehler auf globaler Ebene: Alle Geräte in der Antwort haben denselben Fehler.
• Fehler auf lokaler Ebene: gemischte Antwort mit Fehler- und Erfolgsfällen

Fehler auf globaler Ebene

Das folgende JSON-Snippet zeigt, wie Sie Fehler auf globaler Ebene in einer QUERY- oder EXECUTE-Antwort zurückgeben.

Beispiel für den Fehler deviceOffline auf globaler Ebene, weil der Hub offline ist:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

Ein Beispiel für einen Fehler auf globaler Ebene inSoftwareUpdate aufgrund der Aktualisierung des Hubs:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

Fehler auf Geräteebene

QUERY-Antwort

Das folgende JSON-Snippet zeigt, wie Fehler auf Geräteebene in der QUERY-Antwort zurückgegeben werden.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

EXECUTE-Antwort

Das folgende JSON-Snippet zeigt, wie du Fehler auf Geräteebene in der EXECUTE-Antwort zurückgibst.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

Benachrichtigungen mit Fehlern

Proaktive Benachrichtigung

Das folgende JSON-Snippet zeigt, wie du Fehler auf Geräteebene in einer proaktiven Benachrichtigung meldest.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

Follow-up-Antwort

Das folgende JSON-Snippet zeigt, wie du Fehler auf Geräteebene in einer Folgeantwort meldest.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

Fehlerliste

Die folgenden Fehler führen zu den zugehörigen TTS-Ausgaben auf dem Gerät.

Berichterstellung zum Online- und Offlinestatus

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Ausnahmen

Sie sollten eine Ausnahme zurückgeben, wenn ein Problem oder eine Warnung im Zusammenhang mit einem Befehl vorliegt. Der Befehl kann erfolgreich sein oder fehlschlagen.

Wenn der Befehl erfolgreich war (Status = „SUCCESS“), melde Ausnahmen mit dem Attribut StatusReport (für andere Geräte als das Zielgerät) oder durch Rückgabe eines entsprechenden exceptionCode (für das Zielgerät).

Wenn beispielsweise das Flusensieb des Trockners voll ist, kann der Nutzer den Trockner trotzdem starten. Du solltest ihn aber auf diesen Zustand hinweisen. Wenn der Akkustand eines Geräts niedrig, aber nicht leer ist, kannst du einen Befehl ausführen, solltest den Nutzer aber darüber informieren, dass der Akkustand niedrig ist.

Wenn der Befehl aufgrund von Ausnahmen fehlschlägt, sollte der Status „EXCEPTIONS“ lauten und die Ausnahmen sollten mit dem Attribut StatusReport gemeldet werden.

Nicht blockierende Ausnahme (SUCCESS) für das Zielgerät

In diesem Beispiel wird die Tür verriegelt:

Die Batterie des Schlosses an der Haustür ist schwach. Ich verriegele die Haustür.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Nicht blockierende Ausnahme (SUCCESS) zu einem anderen Gerät, das StatusReport verwendet

In diesem Beispiel wird ein Sicherheitssystem scharf geschaltet: Ok, ich schalte das Sicherheitssystem scharf. Das Fenster vorne ist offen.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

Blockierungsausnahme für ein anderes Gerät, das StatusReport verwendet

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}

Ausnahmeliste

Die folgenden Ausnahmen erzeugen die zugehörige TTS auf dem Gerät.