Senden von C2D-Nachrichten von einem IoT-Hub

  • Artikel

Für das Senden von unidirektionalen Benachrichtigungen von Ihrem Lösungs-Back-End an die Geräte-App senden Sie C2D-Nachrichten von Ihrem IoT-Hub an Ihr Gerät. Eine Erläuterung anderer C2D-Optionen, die von Azure IoT Hub unterstützt werden, finden Sie im Leitfaden zur C2D-Kommunikation.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

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.

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:

Diagramm: Lebenszykluszustands-Diagramm von C2D-Nachrichten.

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ät eine Nachricht empfangen möchte, sperrt der IoT-Hub die Nachricht, indem er den Status auf Unsichtbar 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 abschließt, wird der IoT-Hub hierüber durch den Abschluss der Nachricht benachrichtigt. 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. 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 werden Nachrichten automatisch vom Status Nicht sichtbar zurück in den Status Zur Warteschlange hinzugefügt versetzt, wenn ein Timeout für die Sichtbarkeit (oder Sperrung) abgelaufen ist. Der Wert dieses Timeouts ist auf eine Minute festgelegt 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. Weitere Informationen finden Sie unter Nachrichtenablauf (Gültigkeitsdauer).

Im Artikel Senden von C2D-Nachrichten mit IoT Hub erfahren Sie, wie Sie C2D-Nachrichten über IoT Hub aus der Cloud senden und auf einem Gerät empfangen.

Normalerweise werden C2D-Nachrichten immer dann vom Gerät abgeschlossen, wenn der Verlust der Nachricht keine Auswirkung auf die Anwendungslogik hat. Dieser Abschluss wäre z. B. der Fall, wenn das Gerät den Nachrichteninhalt lokal gespeichert hat oder ein Vorgang erfolgreich ausgeführt wurde. 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:

  • Die C2D-Nachricht nach Speichern der Aufgabenbeschreibung im lokalen Speicher des Geräts abschließen.

  • 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. Diese Zeit wird mittels einer der folgenden Optionen festgelegt:

  • Die ExpiryTimeUtc-Eigenschaft im Dienst
  • Den IoT-Hub durch Verwendung der als IoT-Hub-Eigenschaft angegebenen standardmäßigen Gültigkeitsdauer

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. Bei diesem Ansatz wird das gleiche Ergebnis erzielt wie beim Aufrechterhalten des Geräteverbindungsstatus, er ist aber effizienter. Wenn Sie Nachrichtenbestätigungen anfordern, teilt der IoT-Hub Ihnen mit, für welche Geräte Folgendes zutrifft:

  • In der Lage, Nachrichten zu empfangen.
  • Nicht online oder fehlerhaft.

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:

Ack-Eigenschaftswert Verhalten
Keine Standard. Der IoT-Hub generiert keine Feedbacknachricht.
Positiv Wenn die C2D-Nachricht den Status Abgeschlossen erreicht, generiert der IoT-Hub eine Feedbacknachricht.
Negativ Wenn die C2D-Nachricht den Status Unzustellbar erreicht, generiert der IoT-Hub eine Feedbacknachricht.
Voll Der IoT-Hub generiert in beiden Fällen eine Feedbacknachricht.

Wenn der Ack-Eigenschaftswert auf Voll 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 im Abschnitt Endpunkte erläutert, übermittelt der IoT-Hub Feedback in Form von Nachrichten über einen dienstseitigen Endpunkt (/messages/servicebound/feedback). 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:

Eigenschaft BESCHREIBUNG
EnqueuedTime Ein Zeitstempel, der angibt, wann die Feedbacknachricht vom Hub empfangen wurde.
UserId {iot hub name}
ContentType application/vnd.microsoft.iothub.feedback.json

Das System sendet Feedback, sobald eine der folgenden Bedingungen erfüllt ist: Der Batch umfasst 64 Nachrichten, oder es sind seit dem letzten Sendevorgang 15 Sekunden vergangen.

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

Eigenschaft BESCHREIBUNG
EnqueuedTimeUtc Ein Zeitstempel, der den Zeitpunkt des Nachrichtenergebnisses angibt. Beispielsweise ein Zeitstempel, der angibt, wann der Hub die Feedbacknachricht erhalten hat oder die ursprüngliche Nachricht abgelaufen ist.
originalMessageId Die MessageId der C2D-Nachricht, auf die sich das Feedback bezieht.
statusCode Eine in Feedbacknachrichten verwendete erforderliche Zeichenfolge, die vom IoT-Hub generiert wird:
Erfolgreich
Abgelaufen
DeliveryCountExceeded
Rejected (Abgelehnt)
Gelöscht
description Zeichenfolgenwerte für StatusCode.
deviceId Die DeviceId des Zielgeräts für die C2D-Nachricht, auf die sich das Feedback bezieht.
DeviceGenerationId Die DeviceGenerationId des Zielgeräts für die C2D-Nachricht, auf die sich das Feedback bezieht.

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:

Eigenschaft BESCHREIBUNG Bereich und Standardwert
defaultTtlAsIso8601 Standardmäßige Gültigkeitsdauer für C2D-Nachrichten ISO_8601-Intervall bis zu zwei Tage (mindestens eine Minute). Standardwert: Eine Stunde
maxDeliveryCount Maximale Zustellungsanzahl für C2D-Gerätewarteschlangen pro Gerät 1 bis 100; Standard: 10
feedback.ttlAsIso8601 Aufbewahrungsdauer für dienstgebundene Feedbacknachrichten ISO_8601-Intervall bis zu zwei Tage (mindestens eine Minute). Standardwert: Eine Stunde
feedback.maxDeliveryCount Maximale Zustellungsanzahl für die Feedbackwarteschlange 1 bis 100; Standard: 10
feedback.lockDurationAsIso8601 Sperrdauer für die Feedbackwarteschlange ISO_8601-Intervall zwischen 5 und 300 Sekunden (mindestens fünf Sekunden). Standardwert: 60 Sekunden.

Sie können die Konfigurationsoptionen auf eine der folgenden Weisen 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 Eigenschaften feedback.maxDeliveryCount und feedback.lockDurationAsIso8601 im Azure-Portal wird derzeit nicht unterstützt.)

Festlegen von Konfigurationsoptionen für Cloud-zu-Gerät-Nachrichten im Portal

  • 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 den Empfang von C2D-Nachrichten verwenden können, finden Sie unter Azure IoT Hub-SDKs.

Wenn Sie den Empfang von C2D-Nachrichten testen möchten, absolvieren Sie das Tutorial Senden von C2D-Nachrichten.