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, falls Sie diese implementiert haben, 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, zeigt Google Assistant Nutzern eine allgemeine Fehlermeldung an, z. B. „Entschuldigen Sie, Gerät ist momentan 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 verriegelt oder entriegelt werden kann, sollte dem Nutzer ein Fehler zu diesem Zustand zurückgegeben werden.

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

Wenn ein Gerät offline ist, solltest du {"online": false} innerhalb von 5 Minuten nach dem Auftreten des Geräteproblems an Report State melden.

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

Beispiel für den Fehler inSoftwareUpdate auf globaler Ebene aufgrund einer Aktualisierung des Hubs:

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

Fehler auf Geräteebene

QUERY-Antwort

Im folgenden JSON-Snippet wird gezeigt, wie Sie Fehler auf Geräteebene in der QUERY-Antwort zurückgeben.

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

EXECUTE-Antwort

Im folgenden JSON-Snippet wird gezeigt, wie Sie Fehler auf Geräteebene in der EXECUTE-Antwort 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

Im folgenden JSON-Snippet wird gezeigt, 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"
          }
        }
      }
    }
  }
}

Antwort auf Nachfrage

Im folgenden JSON-Snippet wird gezeigt, 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"
            }
          }
        }
      }
    }
  }
}

Fehlerliste

Bei den folgenden Fehlern wird die zugehörige TTS-Datei auf dem Gerät wiedergegeben.

Ausnahmen

Sie sollten eine Ausnahme zurückgeben, wenn mit einem Befehl ein Problem oder eine Benachrichtigung verbunden ist. Der Befehl kann erfolgreich oder fehlgeschlagen sein.

Wenn der Befehl erfolgreich war (Status = „SUCCESS“), melden Sie Ausnahmen mithilfe des Attributs StatusReport (für andere Geräte als das Ziel) oder indem Sie eine geeignete exceptionCode zurückgeben (für das Zielgerät).

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

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

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

In diesem Beispiel wird die Tür verschlossen:

Die Batterie des Schlosses der Haustür 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 (ERFOLG) zu einem anderen Gerät mit StatusReport

In diesem Beispiel wird ein Sicherheitssystem scharf geschaltet: Ok, ich schaffe das. Das vordere Fenster 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 TTS-Datei auf dem Gerät erstellt.