Beispiele für Schatten-Dokumente Dokumenteigenschaften Delta-Status Versioning von Schattendokumenten Client-Tokens in Schattendokumenten Eigenschaften des leeren Schattendokuments Array-Werte in Schattendokumenten

Dokumente des Device Shadow-Services

Der Device Shadow-Service befolgt alle Regeln der JSON-Spezifikation. Werte, Objekte und Arrays werden im Geräteschatten-Dokument gespeichert.

Inhalt

Beispiele für Schatten-Dokumente
Dokumenteigenschaften
Delta-Status
Versioning von Schattendokumenten
Client-Tokens in Schattendokumenten
Eigenschaften des leeren Schattendokuments
Array-Werte in Schattendokumenten

Beispiele für Schatten-Dokumente

Der Device Shadow-Service verwendet bei den Operationen UPDATE, GET und DELETE mithilfe der REST-API oder MQTT- Pub/Sub-Nachrichten die folgenden Dokumente.

Beispiele

Anfragestatusdokument
Antwortstatusdokumente
Fehlerantwortdokument
Antwortdokument für die Schattennamenliste

Anfragestatusdokument

Ein Anfragestatusdokument hat das folgende Format:


{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}

state – Aktualisierungen betreffen lediglich die angegebenen Felder. In der Regel verwenden Sie entweder die desired- oder die reported-Eigenschaft, aber nicht beide, in derselben Anforderung.
- desired – Die Statuseigenschaften und Werte, deren Aktualisierung im Gerät angefordert wurde.
- reported – Die vom Gerät gemeldeten Zustandseigenschaften und -werte.
clientToken – Falls verwendet, können Sie die Anfrage und die entsprechende Antwort anhand des Client-Tokens abgleichen.
version — Bei Verwendung verarbeitet der Device Shadow-Service nur dann die Aktualisierung, wenn die angegebene Version mit seiner neuesten Version übereinstimmt.

Antwortstatusdokumente

Antwortstatusdokumente haben je nach Antworttyp das folgende Format.

Antwortstatusdokument „/accepted“


{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

Antwortstatusdokument „/delta“


{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
    },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/Dokumente, Antwortstatusdokument


{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}

Eigenschaften des Antwortstatusdokuments

previous – Enthält nach einer erfolgreichen Aktualisierung den state des Objekts vor dem Update.
current – Enthält nach einer erfolgreichen Aktualisierung den state des Objekts nach dem Update.
state
- reported – Liegt nur dann vor, wenn ein Objekt Daten im reported-Abschnitt gemeldet hat, und enthält nur Felder, die im Anfragestatusdokument enthalten waren.
- desired – Liegt nur dann vor, wenn ein Gerät Daten im desired-Abschnitt gemeldet hat, und enthält nur Felder, die im Anfragestatusdokument enthalten waren.
- delta – Liegt nur dann vor, wenn sich die desired-Daten von den aktuellen reported-Daten des Schattens unterscheiden.
metadata –desired Enthält für jedes Attribut in den Abschnitten und reported die Zeitstempel, sodass Sie feststellen können, wann der Status aktualisiert wurde.
timestamp – Datum und Uhrzeit der Epoche, zu der die Antwort von generiert wurde AWS IoT.
clientToken – Liegt nur dann vor, wenn bei der Veröffentlichung einer gültigen JSON im Thema /update ein Client-Token verwendet wurde.
version – Die aktuelle Version des Dokuments für den Geräteschatten, freigegeben in AWS IoT. Sie erhöht sich zur vorherigen Versionsnummer des Dokuments um die Zahl eins.

Fehlerantwortdokument

Ein Fehlerantwortdokument hat das folgende Format:


{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

code – Einen HTTP-Antwortcode, der auf die Art des Fehlers hinweist.
message – Eine Textnachricht mit zusätzlichen Informationen.
timestamp – Das Datum und die Uhrzeit, zu der die Antwort von generiert wurde AWS IoT. Diese Eigenschaft ist nicht in allen Fehlerantwortdokumenten vorhanden.
clientToken – Liegt nur dann vor, wenn ein Client-Token in der veröffentlichten Nachricht verwendet wurde.

Weitere Informationen finden Sie unter Device Shadow-Fehlermeldungen.

Antwortdokument für die Schattennamenliste

Ein Antwortdokument für die Schattennamenliste hat das folgende Format:


{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}

results – Das Array von Schattennamen.
nextToken – Der Token-Wert, der in nach Seiten organisierten Anforderungen verwendet wird, um die nächste Seite in der Sequenz abzurufen. Diese Eigenschaft ist nicht vorhanden, wenn keine weiteren Schattennamen zurückgegeben werden sollen.
timestamp – Das Datum und die Uhrzeit, zu der die Antwort von generiert wurde AWS IoT.

Dokumenteigenschaften

Ein Geräteschatten-Dokument besitzt die folgenden Eigenschaften:

state

desired: Den gewünschte Status des Geräts. Anwendungen können diesen Teil des Dokuments beschreiben, um den Status eines Geräts zu aktualisieren, ohne direkt mit diesem verbunden zu sein.
reported: Der gemeldete Status des Geräts. Geräte schreiben in diesen Teil des Dokuments, um ihren neuen Status zu melden. Apps lesen diesen Teil des Dokuments, um den zuletzt gemeldeten Zustand des Geräts zu bestimmen.

metadata

Informationen über die im Abschnitt state (Status) des Dokuments gespeicherten Daten. Dazu zählen Zeitstempel, in Epoche-Uhrzeit, für das jeweilige Attribut im Abschnitt state (Status), anhand derer Sie den Zeitpunkt ermitteln können, zu dem sie aktualisiert wurden.

Anmerkung

Metadaten zählen nicht zur Dokumentengröße für Service Limits oder Preise. Weitere Informationen finden Sie unter Service Limits AWS IoT.

timestamp

Gibt an, wann die Nachricht von gesendet wurde AWS IoT. Durch Verwendung des Zeitstempels in der Nachricht und der Zeitstempel für einzelne Attribute im Abschnitt desired oder reported kann ein Gerät das Alter einer Eigenschaft bestimmen, selbst wenn das Gerät über keine interne Uhr verfügt.

clientToken

Eine für das Gerät einmalige Zeichenfolge, die es Ihnen ermöglicht, Anfragen in einer MQTT-Umgebung Antworten zuzuordnen.

version

Die Dokumentversion. Jedes Mal, wenn das Dokument aktualisiert wird, erhöht sich diese Versionsnummer. Wird verwendet, um sicherzustellen, dass die Versionsnummer des aktualisierten Dokuments die neueste ist.

Weitere Informationen finden Sie unter Beispiele für Schatten-Dokumente.

Delta-Status

Der Delta-Status ist ein virtueller Typ eines Status, in dem der Unterschied zwischen dem Status desired (Soll) Status und dem Status reported (gemeldet) enthalten ist. Felder im Abschnitt desired (Soll), die nicht im Abschnitt reported (gemeldet) enthalten sind, sind im Delta enthalten. Felder, die im Abschnitt reported (gemeldet) und nicht im Abschnitt desired (Soll) enthalten sind, sind nicht im Delta enthalten. Das Delta enthält Metadaten und seine Werte entsprechen den Metadaten im Feld desired (Soll). Beispielsweise:


{
  "state": {
    "desired": {
      "color": "RED",
      "state": "STOP"
    },
    "reported": {
      "color": "GREEN",
      "engine": "ON"
    },
    "delta": {
      "color": "RED",
      "state": "STOP"
    }
  },
  "metadata": {
    "desired": {
      "color": {
        "timestamp": 12345
      },
      "state": {
        "timestamp": 12345
      }
      },
      "reported": {
        "color": {
          "timestamp": 12345
        },
        "engine": {
          "timestamp": 12345
        }
      },
      "delta": {
        "color": {
          "timestamp": 12345
        },
        "state": {
          "timestamp": 12345
        }
      }
    },
    "version": 17,
    "timestamp": 123456789
  }
}

Wenn die verschachtelten Objekte differieren, enthält das Delta den Pfad bis hin zum Stammverzeichnis.


{
  "state": {
    "desired": {
      "lights": {
        "color": {
          "r": 255,
          "g": 255,
          "b": 255
        }
      }
    },
    "reported": {
      "lights": {
        "color": {
          "r": 255,
          "g": 0,
          "b": 255
        }
      }
    },
    "delta": {
      "lights": {
        "color": {
          "g": 255
        }
      }
    }
  },
  "version": 18,
  "timestamp": 123456789
}

Der Device Shadow-Service berechnet das Delta, indem er jedes einzelne Feld im Status desired (Soll) durchläuft und mit dem Status reported (gemeldet) abgleicht.

Arrays werden wie Werte behandelt. Stimmt ein Array im Abschnitt desired (Soll) nicht mit dem Array im Abschnitt reported (gemeldet) überein, dann wird das gesamte "Soll”-Array in das Delta kopiert.

Versioning von Schattendokumenten

Der Device Shadow-Service unterstützt das Versioning für jede Aktualisierungsnachricht, sowohl Anforderung als auch Antwort. Dies bedeutet, dass bei jeder Aktualisierung eines Schattens die Version des JSON-Dokuments erhöht wird. Dies gewährleistet Folgendes:

Ein Client kann eine Fehlermeldung empfangen, wenn versucht wird, einen Schatten mit einer älteren Versionsnummer zu überschreiben. Der Client wurde darüber informiert, dass eine neue Synchronisation erfolgen muss, bevor ein Geräteschatten aktualisiert werden kann.
Ein Client kann entscheiden, bei einer erhaltenen Nachricht nicht tätig zu werden, wenn die Nachricht über eine niedrigere Version verfügt als die vom Client gespeicherte Version.

Ein Client kann den Versionsabgleich umgehen, indem er keine Version in das Schattendokument aufnimmt.

Client-Tokens in Schattendokumenten

Bei MQTT-basiertem Messaging können Sie einen Client-Token verwenden, um zu überprüfen, ob derselbe Client-Token in einer Anfrage und Antwort auf eine Anfrage enthalten ist. Dies stellt sicher, dass Antwort und Anfrage miteinander verknüpft sind.

Anmerkung

Das Client-Token darf nicht länger als 64 Bytes sein. Ein Client-Token, das länger als 64 Bytes ist, verursacht eine 400er-Antwort (Bad Request) und die Fehlermeldung Invalid clientToken (Ungültiges Client-Token).

Eigenschaften des leeren Schattendokuments

Die Eigenschaften reported und desired in einem Schattendokument können leer sein oder weggelassen werden, wenn sie nicht für den aktuellen Schattenstatus gelten. Ein Schattendokument enthält beispielsweise nur dann eine desired-Eigenschaft, wenn es einen gewünschten Status hat. Der folgende Code ist ein gültiges Beispiel für ein Statusdokument ohne desired-Eigenschaft:


{
    "reported" : { "temp": 55 }
}

Die reported-Eigenschaft kann auch leer sein, z. B. wenn der Schatten nicht vom Gerät aktualisiert wurde:


{
    "desired" : { "color" : "RED" }
}

Wenn eine Aktualisierung bewirkt, dass die Eigenschaft desired oder reported null wird, wird diese aus dem Dokument entfernt. Nachfolgend wird gezeigt, wie Sie die desired-Eigenschaft entfernen, indem Sie sie auf null festlegen. Sie können dies beispielsweise tun, wenn ein Gerät seinen Status aktualisiert.


{ 
    "state": {
        "reported": {
            "color": "red" 
        }, 
        "desired": null 
    } 
}

Ein Schattendokument kann auch keine desired- oder reported-Eigenschaft haben, wodurch das Schattendokument leer wird. Dies ist ein Beispiel für ein leeres, aber gültiges Schattendokument.

{
}

Array-Werte in Schattendokumenten

Schatten unterstützen zwar Arrays, können diese jedoch so als normale Werte behandeln, dass bei einer Aktualisierung eines Arrays das gesamte Array ersetzt wird. Es ist nicht möglich, einen Teil eines Arrays zu aktualisieren.

Ursprungszustand:


{
    "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}

Aktualisieren:


{
    "desired" : { "colors" : ["RED"] }
}

Endzustand:


{
    "desired" : { "colors" : ["RED"] }
}

Arrays können keine Nullwerte besitzen. Das folgende Array ist z. B. ungültig und wird abgelehnt.


{
    "desired" : { 
        "colors" : [ null, "RED", "GREEN" ]
    }
}

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

MQTT-Themen für Geräteschatten

Device Shadow-Fehlermeldungen