Fehler und Ausnahmen

In diesem Dokument werden 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, falls Sie diese implementiert haben, damit Google Assistant Endnutzer auf Probleme im Zusammenhang mit einem bestimmten Befehl oder Gerätestatus aufmerksam macht. Wenn die Antwort eine falsche Formatierung oder errorCode enthält, gibt Google Assistant den Nutzern eine allgemeine Fehlermeldung aus, z. B. „Gerät ist derzeit nicht verfügbar“.

Fehler

Sie sollten 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 dem Nutzer eine Fehlermeldung zu diesem Zustand angezeigt werden.

Fehlercodes können auf Geräteebene oder global angehängt werden. Wenn ein Nutzer beispielsweise viele Lampen von einem Anbieter hat, die über einen Hub gesteuert werden, und er 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 der Verwendung von Fehlern auf globaler Ebene oder 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.

Ein Beispiel für einen Fehler auf globaler Ebene deviceOffline aufgrund des Hubs ist, dass 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 du Fehler auf Geräteebene in der QUERY-Antwort zurückgibst.

{
  "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 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-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 zur entsprechenden Sprachausgabe 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 Benachrichtigung mit einem Befehl verknüpft ist. Der Befehl kann erfolgreich sein oder fehlschlagen.

Wenn der Befehl erfolgreich ausgeführt wurde (status = „SUCCESS“), melden Sie Ausnahmen mit dem StatusReport-Trait (für andere Geräte als das Zielgerät) oder durch Zurückgeben eines entsprechenden exceptionCode (für das Zielgerät).

Wenn beispielsweise das Flusensieb des Trockners voll ist, kann der Nutzer den Trockner trotzdem starten. Sie sollten ihn aber vor diesem Zustand warnen. Wenn ein Gerät einen niedrigen Akkustand hat, der nicht leer ist, kannst du trotzdem einen Befehl ausführen, solltest den Nutzer aber 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 StatusReport-Trait gemeldet werden.

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

Hier ein Beispiel für das Verriegeln der Tür:

Die Batterie des Haustürschlosses ist schwach. Die Eingangstü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) bezüglich eines anderen Geräts, das StatusReport verwendet

Hier ist ein Beispiel für das Scharfschalten eines Sicherheitssystems: Ok, das Sicherheitssystem wird scharf geschaltet. Die Windschutzscheibe 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"
        }]
      }
    }]
  }
}

Blockierungsausnahme für ein anderes Gerät mit StatusReport

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

Bei den folgenden Ausnahmen wird die zugehörige Sprachausgabe auf dem Gerät wiedergegeben.