Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Dokumente des Device Shadow-Services

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

Beispiele für Schatten-Dokumente

Der Device Shadow-Dienst verwendet diese Dokumente in UPDATEGET, und DELETE Operationen mit den RESTAPIoder MQTTPub/Sub-Nachrichten.

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
}

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

Fehlerantwortdokument

Ein Fehlerantwortdokument hat das folgende Format:

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

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
}

Dokumenteigenschaften

Ein Geräteschatten-Dokument besitzt die folgenden Eigenschaften:

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. Das bedeutet, dass bei jeder Aktualisierung eines Shadows die Version des JSON Dokuments inkrementiert wird. Dies gewährleistet Folgendes:

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

Client-Tokens in Schattendokumenten

Sie können ein Client-Token mit MQTT basiertem Messaging verwenden, um zu überprüfen, ob dasselbe Client-Token in einer Anfrage und einer Anforderungsantwort enthalten ist. Dies stellt sicher, dass Antwort und Anfrage miteinander verknüpft sind.

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