Fehler und Ausnahmen

In diesem Dokument sind die offiziell unterstützten Fehler und Ausnahmen für Smart-Home-Geräte aufgeführt. Smart-Home-Geräte. Bitte verwenden Sie diese angegebenen Fehler- und Ausnahmecodes im Intent oder in Benachrichtigungen Google Assistant verwendet, um Endnutzer auf Probleme im Zusammenhang mit gegebener Befehl oder Gerätestatus. Wenn die Antwort eine falsche Formatierung oder errorCode gibt Google Assistant Nutzern eine allgemeine Fehlermeldung aus, z. B.: „Das Gerät ist momentan nicht verfügbar.“

Fehler

Sie sollten einen Fehlercode zurückgeben, wenn ein Problem eine Ausführung oder schlägt fehl. Wenn z. B. ein Türschloss klemmt und gesperrt oder entsperrt, sollte ein Fehler zu diesem Status an den Nutzer zurückgegeben werden.

Fehlercodes können auf Geräte- oder globaler Ebene angehängt werden. Beispiel: Nutzende mehrere Lampen von einem Anbieter haben und diese von einem Hub gesteuert werden, wenn der Nutzer alle Lampen ausschaltet, kann der Dienstleister eine Fehler auf Geräteebene, wenn eine einzelne Lampe offline ist, oder globaler Fehler, wenn der gesamte Hub ist offline und es kann kein Licht gesteuert werden. Wenn alle Geräte offline sind, gibt es keinen Unterschied zwischen globaler und Geräteebene. Fehler. Wenn ein Gerät offline ist, solltest du den Status {"online": false} melden in reportState abrufen, selbst wenn Sie den deviceOffline-Fehlercode.

Zusammenfassung:

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

Fehler auf globaler Ebene

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

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 globalen Fehler inSoftwareUpdate aufgrund des Hubs ist Aktualisierung:

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

Fehler auf Geräteebene

Antwort für QUERY

Das folgende JSON-Snippet zeigt, wie Sie Fehler auf Geräteebene in der QUERY-Antwort.

{
  "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 Sie Fehler auf Geräteebene in der EXECUTE-Antwort.

{
  "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 Sie Fehler auf Geräteebene in einem proaktive Benachrichtigung.

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

Antwort

Das folgende JSON-Snippet zeigt, wie Sie Fehler auf Geräteebene in einem Anschlussantwort.

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

Bei folgenden Fehlern wird die zugehörige Sprachausgabe auf dem Gerät erzeugt.

Ausnahmen

Sie sollten eine Ausnahme zurückgeben, wenn ein Problem oder eine Benachrichtigung mit einer . Der Befehl kann erfolgreich oder fehlschlagen.

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

Wenn beispielsweise das Flusensieb des Trockners voll ist, kann der Nutzer seine trocknen, aber Sie sollten ihn vor diesem Zustand warnen. Ähnlich verhält es sich, wenn ein Gerät einen niedrigen Akkustand hat, aber nicht leer ist, können Sie trotzdem einen Befehl sollte sie aber wissen lassen, dass der Akku des Geräts schwach ist.

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

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

In diesem Beispiel wird die Tür verriegelt:

Die Batterie des Haustürschlosses ist schwach. 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 (ERFOLG) für ein anderes Gerät, für das StatusReport verwendet wird

In diesem Beispiel wird ein Sicherheitssystem scharf geschaltet: Ok, das Sicherheitssystem wird scharf geschaltet. Das Fenster vorne 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 mithilfe von 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

Durch die folgenden Ausnahmen wird die zugehörige Sprachausgabe auf dem Gerät erzeugt.