Interaktion mit Schatten - AWS IoT Core
ProtokollunterstützungAnforderungs- und MeldestatusAktualisieren eines ShadowsAbrufen eines Shadow-DokumentsLöschen von Schattendaten

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.

Interaktion mit Schatten

In diesem Thema werden die Nachrichten beschrieben, die jeder der drei Methoden zugeordnet sind, die AWS IoT für das Arbeiten mit Schatten bereitstellt. Zu diesen Methoden gehören die folgenden:

UPDATE

Erstellt einen Schatten, wenn er nicht vorhanden ist, oder aktualisiert den Inhalt eines vorhandenen Schattens mit den Statusinformationen, die im Nachrichtentext bereitgestellt werden. AWS IoT zeichnet mit jeder Aktualisierung einen Zeitstempel auf, um anzugeben, wann der Status zuletzt aktualisiert wurde. Wenn sich der Status des Schattens ändert, sendet /delta Nachrichten an alle MQTT AWS IoT -Subscriber mit der Differenz zwischen dem desired und dem reported Status. Geräte oder Apps, die eine /delta-Nachricht empfangen, können basierend auf dem Unterschied Aktionen durchführen. Bei einem Gerät kann z. B. der Status auf den Sollstatus oder bei einer Anwendung die Benutzeroberfläche aktualisiert werden, um die Änderung des Gerätestatus zu reflektieren.

GET

Ruft ein aktuelles Schattendokument ab, das den vollständigen Status des Schattens einschließlich Metadaten enthält.

DELETE

Löscht den Geräteschatten und seinen gesamten Inhalt.

Sie können ein gelöschtes Geräteschatten-Dokument nicht wiederherstellen, aber Sie können ein neues Geräteschatten-Dokument mit dem Namen eines gelöschten Geräteschatten-Dokuments erstellen. Wenn Sie ein Geräteschatten-Dokument erstellen, das denselben Namen hat wie eines, das innerhalb der letzten 48 Stunden gelöscht wurde, folgt die Versionsnummer des neuen Geräteschatten-Dokuments der Versionsnummer des gelöschten. Wenn ein Geräteschatten-Dokument länger als 48 Stunden gelöscht wurde, lautet die Versionsnummer eines neuen Geräteschatten-Dokuments mit demselben Namen 0.

Protokollunterstützung

AWS IoT unterstützt MQTT und eine REST-API über HTTPS-Protokolle für die Interaktion mit Schatten. AWS IoT bietet eine Reihe reservierter Anforderungs- und Antwortthemen für MQTT-Veröffentlichungs- und Abonnementaktionen. Geräte und Apps sollten die Antwortthemen abonnieren, bevor sie ein Anforderungsthema veröffentlichen, um Informationen darüber zu erhalten, wie die Anforderung AWS IoT verarbeitet hat. Weitere Informationen finden Sie unter MQTT-Themen für Geräteschatten und Geräteschatten-REST-API.

Anforderungs- und Meldestatus

Beim Entwerfen Ihrer IoT-Lösung mit - AWS IoT und -Schatten sollten Sie die Apps oder Geräte ermitteln, die Änderungen anfordern, und diejenigen, die sie implementieren. In der Regel implementiert und meldet ein Gerät Änderungen an den Schatten zurück, und Apps und Services reagieren auf Änderungen im Schatten und fordern Änderungen an. Ihre Lösung könnte davon abweichen, aber die Beispiele in diesem Thema gehen jedoch davon aus, dass die Client-App oder der Service Änderungen im Schatten anfordert und das Gerät die Änderungen durchführt und sie an den Schatten zurückmeldet.

Aktualisieren eines Shadows

Ihre App oder Ihr Service kann den Status eines Schattens mithilfe der UpdateThingShadow-API oder durch Veröffentlichung im /update-Thema aktualisieren. Aktualisierungen betreffen lediglich die in der Anfrage angegebenen Felder.

Aktualisieren eines Schattens, wenn ein Client eine Statusänderung anfordert

Wenn ein Client eine Statusänderung in einem Schatten mithilfe des MQTT-Protokolls anfordert

  1. Der Client sollte über ein aktuelles Schattendokument verfügen, damit er die zu ändernden Eigenschaften identifizieren kann. Weitere Informationen zum Abrufen des aktuellen Schattendokuments finden Sie unter der Aktion /get.

  2. Der Client abonniert diese MQTT-Themen:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. Der Client veröffentlicht ein $aws/things/thingName/shadow/name/shadowName/update-Anforderungsthema mit einem Statusdokument, das den gewünschten Status des Schattens enthält. Nur die zu ändernden Eigenschaften müssen in das Dokument aufgenommen werden. Dies ist ein Beispiel für ein Dokument mit dem gewünschten Status.

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. Wenn die Aktualisierungsanforderung gültig ist, AWS IoT aktualisiert den gewünschten Status im Schatten und veröffentlicht Nachrichten zu diesen Themen:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    Die /update/accepted-Nachricht enthält ein Antwortstatusdokument „/accepted“-Schattendokument, und die /update/delta-Nachricht enthält ein Antwortstatusdokument „/delta“-Schattendokument.

  5. Wenn die Aktualisierungsanforderung nicht gültig ist, AWS IoT veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/update/rejected Thema mit einem Fehlerantwortdokument Schattendokument, das den Fehler beschreibt.

Wenn ein Client eine Statusänderung in einem Schatten mithilfe der API anfordert

  1. Der Client ruft die UpdateThingShadow-API mit einem Anfragestatusdokument-Statusdokument als Nachrichtentext auf.

  2. Wenn die Anforderung gültig war, AWS IoT gibt einen HTTP-Erfolgsantwortcode und ein Antwortstatusdokument „/accepted“ Schattendokument als Antwortnachrichtentext zurück.

    AWS IoT veröffentlicht auch eine MQTT-Nachricht $aws/things/thingName/shadow/name/shadowName/update/delta mit einem Antwortstatusdokument „/delta“ Schattendokument für alle Geräte oder Clients, die es abonnieren.

  3. Wenn die Anforderung nicht gültig war, AWS IoT gibt einen HTTP-Fehlerantwortcode als Fehlerantwortdokument Antwortnachrichtentext zurück.

Wenn das Gerät den /desired-Status zum /update/delta-Thema erhält, nimmt es die gewünschten Änderungen im Gerät vor. Anschließend wird eine Nachricht an das /update-Thema gesendet, um den aktuellen Status an den Schatten zu melden.

Aktualisieren eines Schattens, wenn ein Gerät seinen aktuellen Status meldet

Wenn ein Gerät seinen aktuellen Status an den Schatten mithilfe des MQTT-Protokolls meldet

  1. Das Gerät sollte diese MQTT-Themen abonnieren, bevor Sie den Schatten aktualisieren:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. Das Gerät meldet seinen aktuellen Status, indem es eine Nachricht zum $aws/things/thingName/shadow/name/shadowName/update-Thema veröffentlicht, das den aktuellen Status meldet, wie etwa in diesem Beispiel.

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. Wenn das Update AWS IoT akzeptiert, veröffentlicht es eine Nachricht zu den $aws/things/thingName/shadow/name/shadowName/update/accepted Themen mit einem Antwortstatusdokument „/accepted“ Schattendokument.

  4. Wenn die Aktualisierungsanforderung nicht gültig ist, AWS IoT veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/update/rejected Thema mit einem Fehlerantwortdokument Schattendokument, das den Fehler beschreibt.

Wenn ein Gerät den aktuellen Status mithilfe der API an den Schatten meldet

  1. Das Gerät ruft die UpdateThingShadow-API mit einem Anfragestatusdokument-Statusdokument als Nachrichtentext auf.

  2. Wenn die Anforderung gültig war, AWS IoT aktualisiert den Schatten und gibt einen HTTP-Erfolgsantwortcode mit einem Antwortstatusdokument „/accepted“ Schattendokument als Antwortnachrichtentext zurück.

    AWS IoT veröffentlicht auch eine MQTT-Nachricht $aws/things/thingName/shadow/name/shadowName/update/delta mit einem Antwortstatusdokument „/delta“ Schattendokument für alle Geräte oder Clients, die es abonnieren.

  3. Wenn die Anforderung nicht gültig war, AWS IoT gibt einen HTTP-Fehlerantwortcode als Fehlerantwortdokument Antwortnachrichtentext zurück.

Optimistische Sperre

Sie können die Version des Statusdokuments verwenden, um sicherzustellen, dass Sie die neueste Version eines Geräteschattendokuments aktualisieren. Geben Sie bei einer Aktualisierungsanfrage eine Version an, lehnt der Service die Anfrage mit einem Konflikt-Antwortcode HTTP 409 ab, wenn die aktuelle Version des Statusdokuments nicht der angegebenen Version entspricht. Der Konfliktreaktionscode kann auch in jeder API vorkommen, die Änderungen am ThingShadow vornimmt, darunter DeleteThingShadow:

Beispielsweise:

Ausgangsdokument:

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

Aktualisierung: (die Versionen stimmen nicht überein; die Anfrage wird abgelehnt)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

Ergebnis:

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

Aktualisierung: (die Versionen stimmen überein; die Anfrage wird angenommen)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

Endzustand:

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

Abrufen eines Shadow-Dokuments

Sie können ein Schattendokument abrufen, indem Sie die GetThingShadow-API verwenden oder indem Sie das /get-Thema abonnieren und dazu veröffentlichen. Hierdurch wird ein vollständiges Schattendokument einschließlich aller Unterschiede zwischen den Statusarten desired und reported abgerufen. Die Vorgehensweise für diese Aufgabe ist unabhängig davon, ob das Gerät oder ein Client die Anforderung durchführt.

So rufen Sie ein Schattendokument mithilfe des MQTT-Protokolls ab:

  1. Das Gerät oder der Client sollte diese MQTT-Themen abonnieren, bevor der Schatten aktualisiert wird:

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. Das Gerät oder der Client veröffentlicht eine Nachricht mit einem leeren Nachrichtentext zum $aws/things/thingName/shadow/name/shadowName/get-Thema.

  3. Wenn die Anforderung erfolgreich ist, AWS IoT veröffentlicht eine Nachricht an das $aws/things/thingName/shadow/name/shadowName/get/accepted Thema mit einem Antwortstatusdokument „/accepted“ im Nachrichtentext.

  4. Wenn die Anforderung nicht gültig war, AWS IoT veröffentlicht eine Nachricht an das $aws/things/thingName/shadow/name/shadowName/get/rejected Thema mit einem Fehlerantwortdokument im Nachrichtentext.

So rufen Sie ein Schattendokument mithilfe einer REST-API ab:

  1. Das Gerät oder Client ruft die GetThingShadow-API mit einem leeren Nachrichtentext auf.

  2. Wenn die Anforderung gültig ist, AWS IoT gibt einen HTTP-Erfolgsantwortcode mit einem Antwortstatusdokument „/accepted“ Schattendokument als Antwortnachrichtentext zurück.

  3. Wenn die Anforderung nicht gültig ist, AWS IoT gibt einen HTTP-Fehlerantwortcode als Fehlerantwortdokument Antwortnachrichtentext zurück.

Löschen von Schattendaten

Es gibt zwei Möglichkeiten, Schattendaten zu löschen: Sie können bestimmte Eigenschaften im Schattendokument löschen oder den Schatten vollständig löschen.

  • Um bestimmte Eigenschaften aus einem Schatten zu löschen, aktualisieren Sie den Schatten. Legen Sie jedoch den Wert der Eigenschaften, die Sie löschen möchten, auf null fest. Felder mit dem Wert null werden aus dem Schattendokument entfernt.

  • Um den gesamten Schatten zu löschen, verwenden Sie die DeleteThingShadow-API oder veröffentlichen Sie zum /delete-Thema.

Anmerkung

Durch das Löschen eines Schattens wird seine Versionsnummer nicht auf einmal auf Null zurückgesetzt. Er wird nach 48 Stunden auf null zurückgesetzt.

Löschen einer Eigenschaft aus einem Schattendokument

So löschen Sie eine Eigenschaft aus einem Schatten mithilfe des MQTT-Protokolls:

  1. Das Gerät oder der Client sollte über ein aktuelles Schattendokument verfügen, damit es/er die zu ändernden Eigenschaften identifizieren kann. Weitere Informationen zum Abrufen des aktuellen Schattendokuments finden Sie unter Abrufen eines Shadow-Dokuments.

  2. Das Gerät oder der Client abonniert diese MQTT-Themen:

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. Das Gerät oder der Client veröffentlicht ein $aws/things/thingName/shadow/name/shadowName/update-Anforderungsthema mit einem Statusdokument, das den Eigenschaften des zu löschenden Schattens null-Werte zuweist. Nur die zu ändernden Eigenschaften müssen in das Dokument aufgenommen werden. Dies ist ein Beispiel für ein Dokument, das die engine-Eigenschaft löscht.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. Wenn die Aktualisierungsanforderung gültig ist, AWS IoT löscht die angegebenen Eigenschaften im Schatten und veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/update/accepted Thema mit einem Antwortstatusdokument „/accepted“ Schattendokument im Nachrichtentext.

  5. Wenn die Aktualisierungsanforderung nicht gültig ist, AWS IoT veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/update/rejected Thema mit einem Fehlerantwortdokument Schattendokument, das den Fehler beschreibt.

So löschen Sie eine Eigenschaft aus einem Schatten mithilfe der REST-API:

  1. Das Gerät oder der Client ruft die UpdateThingShadow-API mit einer Anfragestatusdokument auf die den Eigenschaften des zu löschenden Schattens null-Werte zuweist. Fügen Sie nur die Eigenschaften, die Sie löschen möchten, in das Dokument ein. Dies ist ein Beispiel für ein Dokument, das die engine-Eigenschaft löscht.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. Wenn die Anforderung gültig war, AWS IoT gibt einen HTTP-Erfolgsantwortcode und ein Antwortstatusdokument „/accepted“ Schattendokument als Antwortnachrichtentext zurück.

  3. Wenn die Anforderung nicht gültig war, AWS IoT gibt einen HTTP-Fehlerantwortcode als Fehlerantwortdokument Antwortnachrichtentext zurück.

Löschen eines Shadows

Im Folgenden werden einige Aspekte beschrieben, die beim Löschen des Schattens eines Geräts berücksichtigt werden sollten.

  • Wenn Sie den Schattenstatus des Geräts auf null festlegen, wird der Schatten nicht gelöscht. Die Schattenversion wird beim nächsten Update erhöht.

  • Das Löschen eines Geräteschattens löscht das Objekt nicht. Das Löschen eines Objekts löscht den entsprechenden Geräteschatten nicht.

  • Durch das Löschen eines Schattens wird seine Versionsnummer nicht auf einmal auf Null zurückgesetzt. Er wird nach 48 Stunden auf null zurückgesetzt.

So löschen Sie einen Schatten mithilfe des MQTT-Protokolls:

  1. Das Gerät oder der Client abonniert diese MQTT-Themen:

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. Das Gerät oder der Client veröffentlicht eine $aws/things/thingName/shadow/name/shadowName/delete-mit einem leeren Nachrichtenpuffer.

  3. Wenn die Löschanforderung gültig ist, AWS IoT löscht den Schatten und veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/delete/accepted Thema und einem verkürzten Antwortstatusdokument „/accepted“ Schattendokument im Nachrichtentext. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. Wenn die Aktualisierungsanforderung nicht gültig ist, AWS IoT veröffentlicht eine Nachricht mit dem $aws/things/thingName/shadow/name/shadowName/delete/rejected Thema mit einem Fehlerantwortdokument Schattendokument, das den Fehler beschreibt.

So löschen Sie einen Schatten mithilfe der REST-API:

  1. Das Gerät oder der Client ruft die DeleteThingShadow-API mit einem leeren Nachrichtenpuffer auf.

  2. Wenn die Anforderung gültig war, AWS IoT gibt einen HTTP-Erfolgsantwortcode sowie ein Antwortstatusdokument „/accepted“ und ein abgekürztes Antwortstatusdokument „/accepted“ Schattendokument im Nachrichtentext zurück. Dies ist ein Beispiel für eine akzeptierte Löschmeldung:

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. Wenn die Anforderung nicht gültig war, AWS IoT gibt einen HTTP-Fehlerantwortcode als Fehlerantwortdokument Antwortnachrichtentext zurück.