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.
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.
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 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. Es gibt keine Warteschlange für unzustellbare Nachrichten zum Wiederherstellen 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 werden Nachrichten automatisch vom Status Nicht sichtbar zurück in den Status In Warteschlange eingereiht versetzt, wenn ein Timeout für die Sichtbarkeit (oder Sperrung) abgelaufen ist. Die Länge 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.
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 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 Eigenschaften feedback.maxDeliveryCount und feedback.lockDurationAsIso8601 im Azure-Portal wird derzeit nicht 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.