Fehler und Ausnahmen

In diesem Dokument sind die offiziell unterstützten Fehler und Ausnahmen für Smart-Home-Geräte aufgeführt. Verwenden Sie diese Fehler- und Ausnahmecodes in der Intent-Antwort oder in Benachrichtigungen, wenn Sie sie implementiert haben. Google Assistant benachrichtigt Endnutzer dann über Probleme im Zusammenhang mit einem bestimmten Befehl oder Gerätestatus. Wenn die Antwort eine falsche Formatierung oder errorCode enthält, erhalten Nutzer von Google Assistant eine allgemeine Fehlermeldung, z. B. „Gerät ist derzeit nicht verfügbar“.

Fehler

Sie sollten einen Fehlercode zurückgeben, wenn ein Problem eine Ausführungs- oder Abfrageanfrage auslöst. Wenn beispielsweise ein Türschloss klemmt und nicht ver- oder entriegelt werden kann, sollte ein Fehler über diesen Status an den Nutzer zurückgegeben werden.

Fehlercodes können auf Geräteebene oder auf globaler Ebene angehängt werden. Wenn ein Nutzer beispielsweise viele Lampen von einem Anbieter hat und von einem Hub gesteuert wird, gibt der Nutzer möglicherweise einen Fehler auf Geräteebene zurück, 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 oder Geräteebene. Wenn ein Gerät offline ist, sollten Sie den Status {"online": false} in reportState melden, auch wenn Sie den Fehlercode deviceOffline zurückgeben.

Zusammenfassung:

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

Globale Fehler

Das folgende JSON-Code-Snippet zeigt, wie Sie globale Fehler in der QUERY- oder EXECUTE-Antwort zurückgeben.

Ein Beispiel für den Fehler deviceOffline auf globaler Ebene aufgrund des Hubs ist offline:

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

Ein Beispiel für den Fehler inSoftwareUpdate auf globaler Ebene aufgrund des Hubs wird aktualisiert:

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

Fehler auf Geräteebene

QUERY-Antwort

Das folgende JSON-Code-Snippet zeigt, wie Fehler in der QUERY-Antwort auf Geräteebene 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-Code-Snippet zeigt, wie Sie in der EXECUTE-Antwort Fehler auf Geräteebene zurückgeben.

{
  "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-Code-Snippet zeigt, wie Sie Fehler auf Geräteebene in einer proaktiven Benachrichtigung melden.

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

Folgeantwort

Das folgende JSON-Code-Snippet zeigt, wie Sie Fehler auf Geräteebene in einer Folgeantwort melden.

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

Liste möglicher Fehler

Die folgenden Fehler führen zur entsprechenden Text-in-Sprache-Funktion auf dem Gerät.

Ausnahmen

Sie sollten eine Ausnahme zurückgeben, wenn ein Problem oder eine Benachrichtigung mit einem Befehl verknüpft ist. Der Befehl könnte erfolgreich sein oder fehlschlagen.

Wenn der Befehl erfolgreich war (Status = „SUCCESS“), melden Sie Ausnahmen mit der Eigenschaft StatusReport (für andere Geräte als das Ziel) oder indem Sie ein entsprechendes exceptionCode (für das Zielgerät) zurückgeben.

Wenn der Trocknertuch zum Beispiel voll ist, kann der Nutzer den Trockner trotzdem starten, Sie sollten ihn jedoch auf diesen Zustand warnen. Auch wenn der Akkustand eines Geräts nicht leer ist, können Sie einen Befehl ausführen. Der Nutzer sollte jedoch darüber informiert werden, dass der Akkustand des Geräts 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) auf Zielgerät

In diesem Beispiel wird die Tür verriegelt:

Der Akkustand der Haustür ist niedrig. Die Haustür wird abgeschlossen.

{
  "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) für ein anderes Gerät mit StatusReport

In diesem Beispiel wird das Sicherheitssystem scharf geschaltet: Ok, das System wird scharf geschaltet. Das Fenster auf der Vorderseite ist geöffnet.

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

Ausnahme für ein anderes Gerät wird mit StatusReport blockiert

{
  "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 führen zur zugehörigen Text-in-Sprache-Funktion auf dem Gerät.