Fehler und Ausnahmen

In diesem Dokument werden die offiziell unterstützten Fehler und Ausnahmen für Smart-Home-Geräte aufgeführt. Verwenden Sie die angegebenen Fehler- und Ausnahmecodes in der Intent-Antwort oder in Benachrichtigungen, wenn Sie diese implementiert haben, sodass Google Assistant Endnutzer bei Problemen in Bezug auf einen bestimmten Befehl oder Gerätestatus benachrichtigt. Wenn die Antwort eine falsche Formatierung oder errorCode enthält, erhalten Nutzer von Google Assistant eine allgemeine Fehlermeldung wie „Leider ist Gerät derzeit nicht verfügbar“.

Fehler

Sie sollten einen Fehlercode zurückgeben, wenn ein Problem bei einer Ausführungs- oder Abfrageanfrage fehlschlägt. Wenn beispielsweise eine Türsperre klemmt und nicht ver- oder entriegelt werden kann, sollte ein Fehler zu diesem 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 eines Anbieters hat und von einem Hub gesteuert wird, gibt der Anbieter möglicherweise einen Gerätefehler zurück, wenn eine einzelne Lampe offline ist, oder einen globalen Fehler, 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 auf Geräteebene. Wenn ein Gerät offline ist, sollten Sie den Status {"online": false} im reportState melden, auch wenn Sie den deviceOffline-Fehlercode zurückgeben.

Zusammenfassung:

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

Globale Fehler

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

Ein Beispiel für den globalen Fehler deviceOffline 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-Snippet zeigt, wie in der QUERY-Antwort Fehler 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"
      }
    }
  }
}

AUSFÜHRUNG

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

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

Im folgenden JSON-Snippet sehen Sie, 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

Im folgenden JSON-Snippet sehen Sie, 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 zugehörigen TTS auf dem Gerät.

Ausnahmen

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

Wenn der Befehl erfolgreich war (Status = „SUCCESS“), melden Sie Ausnahmen mit dem Merkmal StatusReport (für andere Geräte als das Ziel) oder geben Sie einen entsprechenden exceptionCode (für das Zielgerät) zurück.

Wenn z. B. ein Trocknertuch vollständig befüllt ist, kann der Nutzer seinen Trockner starten. Es empfiehlt sich aber, ihn auf diesen Zustand zu warnen. Wenn der Akkustand eines Geräts nicht leer ist, können Sie zwar einen Befehl ausführen, aber den Nutzer darüber informieren, 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) zum Zielgerät

In diesem Beispiel wird die Tür verriegelt:

Der Akkustand des Haustürschlosses ist niedrig. Die Haustür abschließen.

{
  "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 mithilfe von StatusReport

In diesem Beispiel wird ein Sicherheitssystem scharf geschaltet: Ok, Sicherheitssystem scharf schalten. Das Fenster auf der Vorderseite 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"
        }]
      }
    }]
  }
}

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

Mit den folgenden Ausnahmen wird die zugehörige TTS auf dem Gerät erstellt.