Nachrichtenanreicherungen bei Gerät-zu-Cloud-IoT Hub-Nachrichten
Nachrichtenanreicherungen ist die Fähigkeit eines IoT-Hubs, Nachrichten mit zusätzlichen Informationen zu stempeln, bevor sie an den angegebenen Endpunkt gesendet werden. Ein Grund für die Verwendung von Nachrichtenanreicherungen: Auf diese Weise lassen sich Daten einbeziehen, die zur Vereinfachung der Downstreamverarbeitung verwendet werden können. So kann beispielsweise durch die Anreicherung von Gerätetelemetrienachrichten mit einem Gerätezwillingstag die Last bei Kunden reduziert werden, um Gerätezwillings-API-Aufrufe für diese Informationen durchzuführen.
Eine Nachrichtenanreicherung besteht aus drei Hauptelementen:
Name oder Schlüssel der Anreicherung
Einem Wert
Einem oder mehreren Endpunkten, bei dem/denen die Anreicherung angewendet werden soll.
Der Schlüssel ist eine Zeichenfolge. Ein Schlüssel darf nur alphanumerische Zeichen oder diese Sonderzeichen enthalten: Bindestrich (-), Unterstrich (_) und Punkt (.).
Der Wert kann eines der folgenden Beispiele sein:
Eine statische Zeichenfolge. Dynamische Werte wie Bedingungen, Logik, Vorgänge und Funktionen sind nicht zulässig. Wenn Sie beispielsweise eine SaaS-Anwendung entwickeln, die von mehreren Kunden verwendet wird, können Sie jedem Kunden einen Bezeichner zuweisen und diesen Bezeichner in der Anwendung zur Verfügung stellen. Bei Ausführung der Anwendung stempelt IoT Hub die Gerätetelemetrienachrichten mit dem Bezeichner des Kunden und ermöglicht es so, dass die Nachrichten bei jedem Kunden anders verarbeitet werden.
Der Name des IoT-Hubs, der die Nachricht sendet. Dieser Wert ist $iothubname.
Informationen aus dem Gerätezwilling, z.B. dessen Pfad. Beispiele hierfür wären $twin.tags.field und $twin.tags.latitude.
Hinweis
Zurzeit werden nur die Variablen „$iothubname“, „$twin.tags“, „$twin.properties.desired“ und „$twin.properties.reported“ für die Nachrichtenanreicherung unterstützt. Außerdem werden nur einfache Typen für Anreicherungen unterstützt. Nachrichten können nicht mit Objekttypen angereichert werden.
Nachrichtenanreicherungen werden den an ausgewählte Endpunkte gesendeten Nachrichten als Anwendungseigenschaften hinzugefügt.
Anwenden von Anreicherungen
Die Nachrichten können aus einer beliebigen Datenquelle stammen, die vom IoT Hub-Nachrichtenrouting unterstützt wird, darunter die folgenden Beispiele:
- Gerätetelemetrie, z.B. Temperatur oder Druck
- Benachrichtigungen zu Änderungen bei Gerätezwillingen – Änderungen am Gerätezwilling
- Ereignisse im Gerätelebenszyklus, z.B. wenn das Gerät erstellt oder gelöscht wird
Sie können Anreicherungen Nachrichten, die an den integrierten Endpunkt eines IoT-Hubs gesendet werden, oder Nachrichten hinzufügen, die an benutzerdefinierte Endpunkte wie Azure Blob Storage, eine Service Bus-Warteschlange oder ein Service Bus-Thema weitergeleitet werden.
Sie können Nachrichten, die in Event Grid veröffentlicht werden, Anreicherungen auch hinzufügen, indem Sie zuerst ein Event Grid-Abonnement mit dem Nachrichtentyp „Gerätetelemetrie“ erstellen. Basierend auf diesem Abonnement erstellen wir in Azure IoT Hub eine Standardroute für die Telemetriedaten. Diese einzelne Route kann alle Ihre Event Grid-Abonnements verarbeiten. Anschließend können Sie Anreicherungen für den Endpunkt über die Registerkarte Nachrichten anreichern im Abschnitt Nachrichtenrouting des IoT Hubs konfigurieren. Informationen zum Reagieren auf Ereignisse mithilfe von Event Grid finden Sie unter Iot Hub und Event Grid.
Anreicherungen werden pro Endpunkt angewendet. Wenn Sie fünf Anreicherungen angeben, die für einen bestimmten Endpunkt gestempelt werden sollen, werden alle an diesen Endpunkt gesendeten Nachrichten mit denselben fünf Anreicherungen gestempelt.
Anreicherungen können mithilfe der folgenden Methoden konfiguriert werden:
| Methode | Befehl |
|---|---|
| Portal | Azure-PortalEntsprechende Informationen finden Sie im Tutorial zu Nachrichtenanreicherungen |
| Azure-Befehlszeilenschnittstelle | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
Das Hinzufügen von Nachrichtenanreicherungen führt zu keiner Latenz beim Nachrichtenrouting.
Wenn Sie Nachrichtenanreicherungen ausprobieren möchten, lesen Sie das Tutorial zu Nachrichtenanreicherungen.
Einschränkungen
Sie können bis zu 10 Anreicherungen pro IoT-Hub für diese Hubs im Standard- oder Basic-Tarif hinzufügen. Bei IoT-Hubs im Free-Tarif können Sie bis zu 2 Anreicherungen hinzufügen.
Wenn Sie eine Nachricht mit einem Wert anreichern, der auf ein Tag oder eine Eigenschaft im Gerätezwilling festgelegt wurde, wird dieser Wert in einigen Fällen mit dem angegebenen Gerätezwillingspfad gestempelt. Wenn beispielsweise ein Anreicherungswert auf „$twin.tags.field“ festgelegt wurde, werden die Nachrichten mit der Zeichenfolge „$twin.tags.field“ statt mit dem Wert dieses Feldes aus dem Zwilling gestempelt. Dieses Verhalten gilt in den folgenden Fällen:
Ihr IoT-Hub ist im Basic-Tarif. IoT-Hubs im Basic-Tarif unterstützen Gerätezwillinge nicht.
Ihr IoT-Hub ist im Standard-Tarif, doch der für den Wert der Anreicherung verwendete Gerätezwillingspfad ist nicht vorhanden. Wenn beispielsweise der Anreicherungswert auf „$twin.tags.location“ festgelegt wurde und es für den Gerätezwilling unter „tags“ keine„location“-Eigenschaft gibt, wird die Nachricht mit der Zeichenfolge „$twin.tags.location“ gestempelt.
Ihr IoT-Hub ist im Standard-Tarif, aber der für den Wert der Anreicherung verwendete Gerätezwillingspfad wird in ein Objekt statt in eine einfache Eigenschaft aufgelöst. Wenn beispielsweise der Anreicherungswert auf „$twin.tags.location“ festgelegt wurde und die Eigenschaft „location“ unter „tags“ ein Objekt ist, das untergeordnete Eigenschaften wie
{"building": 43, "room": 503}enthält, wird die Nachricht mit der Zeichenfolge „$twin.tags.location“ gestempelt.
Bei Updates an einem Gerätezwilling kann es bis zu fünf Minuten dauern, bis sie im entsprechenden Anreicherungswert angezeigt werden.
Die Gesamtgröße der Nachricht, einschließlich der Anreicherungen, darf 256 KB nicht überschreiten. Wenn eine Nachricht größer als 256 KB ist, wird sie vom IoT-Hub gelöscht. Sie können Fehler mithilfe von IoT Hub-Metriken identifizieren und debuggen, wenn Nachrichten gelöscht werden. So können Sie beispielsweise die Metrik Nicht kompatible Telemetrienachrichten (d2c.telemetry.egress.invalid) in den Routingmetriken überwachen. Weitere Informationen finden Sie unter Überwachen von IoT Hub.
Nachrichtenanreicherungen gelten nicht für Änderungsereignisse bei digitalen Zwillingen.
Module erben keine Zwillingstags von deren zugehörigen Geräten. Anreicherungen für Nachrichten, die aus Gerätemodulen stammen (z. B. aus IoT Edge-Modulen), müssen die Zwillingstags verwenden, die für den Modulzwilling festgelegt sind.
Preise
Nachrichtenanreicherungen sind ohne zusätzliche Gebühren verfügbar. Zurzeit fallen für Sie Kosten an, wenn Sie eine Nachricht an einen IoT-Hub senden. Diese Nachricht wird Ihnen nur einmal in Rechnung gestellt – sogar dann, wenn sie an mehrere Endpunkte gesendet wird.
Nächste Schritte
Weitere Informationen zum Weiterleiten von Nachrichten an einen IoT-Hub finden Sie in diesen Artikeln: