Anmerkung
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Nachrichtenerweiterungen sind die Möglichkeit eines IoT-Hubs, Nachrichten mit zusätzlichen Informationen zu stempeln , bevor die Nachrichten 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 weist drei Schlüsselelemente auf:
Name oder Schlüssel der Anreicherung
Ein Wert
Mindestens ein Endpunkt, auf den die Anreicherung angewendet werden soll.
Der Schlüssel ist eine Zeichenfolge. Eine Taste kann nur alphanumerische Zeichen oder diese Sonderzeichen enthalten: Bindestrich (-), Unterstrich (_) und Punkt (.).
Der Wert kann eines der folgenden Beispiele sein:
Eine beliebige 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 verfügbar machen. Wenn die Anwendung ausgeführt wird, stempelt IoT Hub die Telemetrienachrichten des Geräts mit dem Bezeichner des Kunden, sodass die Nachrichten für jeden Kunden unterschiedlich verarbeitet werden können.
Der Name des IoT-Hubs, der die Nachricht sendet. Dieser Wert ist $iothubname.
Informationen aus dem Gerätezwilling, z.B. dessen Pfad. Beispiele 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. Darüber hinaus werden nur primitive Typen für Anreicherungen unterstützt. Nachrichten können nicht mit Objekttypen erweitert werden.
Nachrichtenanreicherungen werden als Anwendungseigenschaften zu Nachrichten hinzugefügt, die an ausgewählte Endpunkte gesendet werden.
Anwenden von Anreicherungen
Die Nachrichten können von jeder Datenquelle stammen, die vom IoT Hub-Nachrichtenrouting unterstützt wird, einschließlich der folgenden Beispiele:
- Gerätetelemetrie, z. B. Temperatur oder Druck
- Geräte-Zwilling-Änderungsbenachrichtigungen – Änderungen am Geräte-Zwilling
- Lebenszyklusereignisse des Geräts, z. B. beim Erstellen oder Löschen des Geräts
Sie können Anreicherungen zu Nachrichten hinzufügen, die an den eingebauten Endpunkt eines IoT-Hubs gehen oder zu Nachrichten, die an benutzerdefinierte Endpunkte wie Azure Blob Storage, eine Service Bus-Warteschlange oder ein Service Bus-Thema weitergeleitet werden.
Sie können Nachrichten, die im Event Grid veröffentlicht werden, auch anreichern, indem Sie zuerst ein Event Grid-Abonnement mit dem Nachrichtentyp "Gerätetelemetrie" erstellen. Basierend auf diesem Abonnement erstellen wir eine Standardroute in Azure IoT Hub für die Telemetrie. Diese einzelne Route kann alle Ihre Event Grid-Abonnements verarbeiten. Anschließend können Sie Anreicherungen für den Endpunkt konfigurieren, indem Sie die Registerkarte "Nachrichten anreichern " des Abschnitts "IoT Hub Message routing" verwenden. Informationen zum Reagieren auf Ereignisse mithilfe von Event Grid finden Sie unter React to IoT Hub-Ereignisse mithilfe von Event Grid zum Auslösen von Aktionen.
Anreicherungen werden pro Endpunkt angewendet. Wenn Sie fünf Anreicherungen angeben, die für einen bestimmten Endpunkt gestempelt werden sollen, werden alle Nachrichten, die zu diesem Endpunkt wechseln, mit denselben fünf Anreicherungen gestempelt.
Anreicherungen können mit den folgenden Methoden konfiguriert werden:
| Methode | Befehl |
|---|---|
| Portal |
Azure-Portal Weitere Informationen finden Sie im Lernprogramm: Verwenden von Azure IoT Hub-Nachrichtenanreicherungen. |
| Azure-Befehlszeilenschnittstelle (Azure CLI) | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
Das Hinzufügen von Nachrichtenanreicherungen fügt keine Latenz zum Nachrichtenrouting hinzu.
Informationen zum Ausprobieren von Nachrichtenanreicherungen finden Sie im Lernprogramm: Verwenden von Azure IoT Hub-Nachrichtenanreicherungen
Einschränkungen
Sie können bis zu 10 Anreicherungen pro IoT-Hub für diese Hubs in der Standard- oder Basisebene hinzufügen. Für IoT-Hubs auf der kostenlosen Ebene können Sie bis zu zwei Anreicherungen hinzufügen.
In einigen Fällen wird der Wert mit dem angegebenen Gerätezwillingspfad gestempelt, wenn Sie eine Nachricht mit einem Wert anreichern, der auf ein Tag oder eine Eigenschaft im Gerätezwilling festgelegt ist. Wenn beispielsweise ein Anreicherungswert auf $twin.tags.field festgelegt ist, werden die Nachrichten mit der Zeichenfolge "$twin.tags.field" und nicht mit dem Wert dieses Felds aus dem Twin versehen. Dieses Verhalten tritt in den folgenden Fällen auf:
Ihr IoT-Hub befindet sich auf der Basisebene. Grundlegende IoT-Hubs unterstützen keine Geräte-Zwillinge.
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 Nachrichtengröße 256 KB überschreitet, legt der IoT-Hub die Nachricht ab. Sie können IoT Hub-Metriken verwenden, um Fehler zu identifizieren und zu debuggen, wenn Nachrichten verworfen 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 Azure IoT Hub.
Nachrichtenanreicherungen gelten nicht für Änderungsereignisse bei digitalen Zwillingen.
Module erben keine Twin-Tags von ihren entsprechenden Geräten. Anreicherungen für Nachrichten, die von Gerätemodulen (z. B. aus IoT Edge-Modulen) stammen, müssen die Twin-Tags verwenden, die auf dem Modul twin festgelegt sind.
Preisgestaltung
Nachrichtenanreicherungen stehen kostenlos zur Verfügung. Derzeit werden Sie belastet, wenn Sie eine Nachricht an einen IoT-Hub senden. Sie werden nur einmal für diese Nachricht belastet, auch wenn die Nachricht an mehrere Endpunkte gesendet wird.
Nächste Schritte
Weitere Informationen zum Weiterleiten von Nachrichten an einen IoT-Hub finden Sie in diesen Artikeln: