Grundlegendes zum Cloud-zu-Gerät-Messaging von einem IoT-Hub

Cloud-zu-Gerät-Nachrichten sind unidirektionale Benachrichtigungen von Ihrem Lösungs-Back-End zu einer Geräteanwendung. Eine Erläuterung anderer C2D-Optionen, die von Azure IoT Hub unterstützt werden, finden Sie im Leitfaden zur C2D-Kommunikation.

Sie senden Cloud-zu-Gerät-Nachrichten (Cloud-to-Device, C2D) über einen dienstseitigen Endpunkt, /messages/devicebound. Ein Gerät empfängt die Nachrichten dann über einen gerätespezifischen Endpunkt, /devices/{Geräte-ID}/messages/devicebound.

Um jede C2D-Nachricht einem bestimmten Gerät zuzuordnen, legt Ihr IoT-Hub die to-Eigenschaft auf /devices/{Geräte-ID}/messages/devicebound fest.

Jede Gerätewarteschlange kann maximal 50 C2D-Nachrichten enthalten. Wenn Sie versuchen, mehr Nachrichten an dasselbe Gerät zu senden, tritt ein Fehler auf.

In diesem Artikel werden die Konzepte und Prozesse rund um Cloud-zu-Gerät-Nachrichten erläutert. Anleitungen zum Entwickeln von Anwendungen, die Cloud-zu-Gerät-Nachrichten verarbeiten, finden Sie unter Senden und Empfangen von Cloud-zu-Gerät-Nachrichten.

Der Lebenszyklus von C2D-Nachrichten

Um die Nachrichtenübermittlung mindestens einmal zu gewährleisten, werden C2D-Nachrichten in Ihrem IoT-Hub in Warteschlangen auf Gerätebasis beibehalten. Geräte müssen den Abschluss einer Nachricht explizit bestätigen, bevor der IoT-Hub die Nachricht aus der Warteschlange entfernt. Auf diese Weise wird Resilienz bei Verbindungs- und Gerätefehlern gewährleistet.

Die Lebenszyklus-Zustandsgrafik wird im folgenden Diagramm dargestellt:

Wenn der IoT-Hub-Dienst eine Nachricht an ein Gerät sendet, legt der Dienst den Nachrichtenstatus auf In Warteschlange eingereiht fest. Wenn ein Gerätethread für den Empfang einer Nachricht bereit ist, sperrt der IoT-Hub die Nachricht, indem er den Status auf Nicht sichtbar setzt. Dieser Zustand ermöglicht, dass andere Threads auf dem Gerät andere Nachrichten empfangen können. Wenn ein Gerätethread die Verarbeitung einer Nachricht abgeschlossen hat, benachrichtigt er den IoT-Hub durch Abschließen der Nachricht. Der IoT-Hub legt dann den Status auf Abgeschlossen fest.

Ein Gerät kann auch Folgendes durchführen:

• Ablehnen der Nachricht: Der IoT-Hub versetzt sie in den Status Unzustellbar. Es gibt keine Warteschleife für die Wiederherstellung dieser Nachrichten. Geräte, die über das MQTT-Protokoll (Message Queuing Telemetry Transport) eine Verbindung herstellen, können C2D-Nachrichten nicht ablehnen.

• Verwerfen der Nachricht: Der IoT-Hub platziert die Nachricht wieder in der Warteschlange mit dem Status Zur Warteschlange hinzugefügt. Geräte, die über das MQTT-Protokoll eine Verbindung herstellen, können C2D-Nachrichten nicht ablehnen.

Bei der Nachrichtenverarbeitung durch den Thread könnte ein Fehler auftreten, ohne dass de IoT-Hub hierüber benachrichtigt wird. In diesem Fall wechseln Nachrichten automatisch vom Unsichtbaren Zustand zurück zum Enqueued-Zustand nach einem Sichtbarkeitstimeout (oder Sperrtimeout). Die Länge dieses Timeouts beträgt eine Minute und kann nicht geändert werden.

Die Eigenschaft Anzahl maximaler Zustellungen im IoT-Hub bestimmt, wie oft eine Nachricht zwischen den Statuswerten In Warteschlange eingereiht und Nicht sichtbar wechseln kann. Nachdem diese Anzahl überschritten wurde, legt der IoT-Hub den Status der Nachricht auf Unzustellbar fest. Ebenso kennzeichnet der IoT-Hub eine Nachricht nach deren Ablaufzeitpunkt als Unzustellbar.

Normalerweise werden C2D-Nachrichten immer dann vom Gerät abgeschlossen, wenn der Verlust der Nachricht keine Auswirkung auf die Anwendungslogik hat. Ein Beispiel für diesen Abschluss kann sein, wenn das Gerät den Nachrichteninhalt lokal speichert oder erfolgreich einen Vorgang ausführt. Die Nachricht könnte auch vorübergehende Informationen übermitteln, deren Verlust die Funktionalität der Anwendung nicht beeinträchtigen würde. Für Aufgaben mit langer Ausführungszeit können Sie:

• Schließen Sie die Meldung "Cloud-zu-Gerät" ab, nachdem das Gerät die Aufgabenbeschreibung im lokalen Speicher beibehalten hat.

• Das Lösungs-Back-End mithilfe von D2C-Nachrichten in verschiedenen Phasen des Aufgabenverlaufs benachrichtigen.

Nachrichtenablauf (Gültigkeitsdauer)

Jede C2D-Nachricht verfügt über eine Gültigkeitsdauer. Eine der folgenden Optionen legt die Ablaufzeit fest:

• Die ExpiryTimeUtc-Eigenschaft im Dienst
• Der IoT-Hub mithilfe der Standardgültigkeitsdauer als IoT-Hubeigenschaft

Weitere Informationen zum Ablauf von Nachrichten finden Sie unter C2D-Konfigurationsoptionen.

Eine gängige Methode, den Vorteil eines Nachrichtenablaufs zu nutzen und zu vermeiden, dass Nachrichten an getrennte Geräte gesendet werden, ist die Festlegung einer kurzen Gültigkeitsdauer für Werte. Dieser Ansatz erzielt dasselbe Ergebnis wie die Aufrechterhaltung des Geräteverbindungszustands, ist aber effizienter. Wenn Sie Nachrichtenbestätigungen anfordern, benachrichtigt der IoT-Hub Sie über die folgenden Geräte:

• Sie können Nachrichten empfangen.
• Sind nicht online oder sind fehlgeschlagen.

Nachrichtenfeedback

Beim Senden einer C2D-Nachricht kann der Dienst das Übermitteln von Feedback auf Nachrichtenbasis anfordern, um über den finalen Status dieser Nachricht informiert zu werden. Sie können Nachrichtenfeedback konfigurieren, indem Sie die Anwendungseigenschaft iothub-ack in der C2D-Nachricht festlegen, die an einen der folgenden vier Werte gesendet wird:

Wenn der Wert der Ack-Eigenschaft auf "vollständig" festgelegt ist und Sie keine Feedbacknachricht erhalten, bedeutet dies, dass die Feedbacknachricht abgelaufen ist. Der Dienst kann nicht wissen, was mit der ursprünglichen Nachricht geschehen ist. In der Praxis sollte ein Dienst sicherstellen, dass Feedback verarbeitet werden kann, bevor es abläuft. Die maximale Ablaufzeit beträgt zwei Tage, sodass ausreichend Zeit verbleibt, um den Dienst wieder zu starten, wenn ein Fehler auftritt.

Wie in IoT Hub-Endpunkten erläutert, liefert der IoT-Hub Feedback über einen dienstorientierten Endpunkt, /messages/servicebound/feedback, als Nachrichten. Die Semantik für den Empfang von Feedback entspricht der Semantik für C2D-Nachrichten. Nachrichtenfeedback wird nach Möglichkeit in einer einzigen Nachricht zusammengefasst, die das folgende Format aufweist:

Das System sendet das Feedback entweder, wenn der Batch bis zu 64 Nachrichten erreicht oder in 15 Sekunden von der letzten Übermittlung, je nachdem, was zuerst kommt.

Der Nachrichtenkörper ist ein serialisiertes JSON-Array aus Datensätzen, von denen jeder die folgenden Eigenschaften aufweist:

Der Dienst muss eine MessageId angeben, damit die C2D-Nachricht das Feedback mit der ursprünglichen Nachricht korrelieren kann.

Das folgende Codebeispiel zeigt den Text einer Feedbacknachricht:

[
  {
    "originalMessageId": "0987654321",
    "enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
    "statusCode": "Success",
    "description": "Success",
    "deviceId": "123",
    "deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
  },
  {
    ...
  },
  ...
]

Ausstehendes Feedback für gelöschte Geräte

Wird ein Gerät gelöscht, wird auch das gesamte ausstehende Feedback gelöscht. Gerätefeedback wird in Batches gesendet. Ein schmales Fenster, oft weniger als eine Sekunde, kann zwischen dem Zeitpunkt auftreten, an dem ein Gerät den Empfang der Nachricht bestätigt, und dem Zeitpunkt, zu dem der nächste Feedbackbatch vorbereitet wird. Wenn ein Gerät in diesem schmalen Fenster gelöscht wird, tritt das Feedback nicht auf.

Sie können dies umgehen, indem Sie warten, bis das ausstehende Feedback eingegangen ist, bevor Sie das Gerät löschen. Nach dem Löschen eines Geräts sollte zugehöriges Nachrichtenfeedback als verloren betrachtet werden.

Optionen für die C2D-Konfiguration

Jede IoT Hub-Instanz legt die folgenden Konfigurationsoptionen für das C2D-Messaging offen:

Sie können die Konfigurationsoptionen im Azure-Portal oder über die Azure CLI festlegen:

• Azure-Portal: Wählen Sie für Ihren IoT-Hub unter Hub-Einstellungen die Option Integrierte Endpunkte aus, und gehen Sie zu Cloud-zu-Gerät-Nachrichten. (Das Festlegen der Eigenschaft feedback.maxDeliveryCount oder feedback.lockDurationAsIso8601 wird derzeit nicht im Azure-Portal unterstützt.)

  

• Azure CLI: Verwenden Sie den Befehl az iot hub update:

  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.defaultTtlAsIso8601=PT1H0M0S
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.maxDeliveryCount=10
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.ttlAsIso8601=PT1H0M0S
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.maxDeliveryCount=10
  
  az iot hub update --name {your IoT hub name} \
      --set properties.cloudToDevice.feedback.lockDurationAsIso8601=PT0H1M0S
  

Nächste Schritte

Informationen zu den SDKs, die Sie für die Verarbeitung von Cloud-zu-Gerät-Nachrichten verwenden können, finden Sie unter Azure IoT Hub-SDKs.

Anleitungen zum Entwickeln von Anwendungen, die Cloud-zu-Gerät-Nachrichten verarbeiten, finden Sie unter Senden und Empfangen von Cloud-zu-Gerät-Nachrichten.