Tutorial: Verwenden von Azure IoT Hub-Nachrichtenanreicherungen

Nachrichtenanreicherungen sind die Fähigkeit von Azure IoT Hub, 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ätenachrichten mit einem Gerätezwillingstag die Last bei Kunden reduziert werden, um Gerätezwillings-API-Aufrufe für diese Informationen durchzuführen. Weitere Informationen finden Sie unter Übersicht über Nachrichtenanreicherungen.

Im ersten Teil dieses Tutorials haben Sie gesehen, wie Sie benutzerdefinierte Endpunkte erstellen und Nachrichten an andere Azure-Dienste weiterleiten. In diesem Tutorial lernen Sie zwei Möglichkeiten zum Erstellen und Konfigurieren der Ressourcen kennen, die zum Testen der Nachrichtenanreicherungen für einen IoT-Hub benötigt werden. Die Ressourcen umfassen einen zweiten Speichercontainer für ein vorhandenes Speicherkonto (erstellt im ersten Teil des Tutorials), um die angereicherten Nachrichten und eine Nachrichtenroute zu speichern, um sie dort zu senden. Nachdem die Konfigurationen für das Nachrichtenrouting und die Nachrichtenanreicherungen abgeschlossen wurden, verwenden Sie eine Anwendung, um Nachrichten an den IoT-Hub zu senden. Der Hub leitet sie dann an beide Speichercontainer weiter. Nur die an den Endpunkt für den Speichercontainer enriched gesendeten Nachrichten werden angereichert.

In diesem Tutorial führen Sie die folgenden Aufgaben aus:

• Erstellen Sie einen Container in Ihrem Speicherkonto.
• Erstellen eines benutzerdefinierten Endpunkts für das Speicherkonto und Weiterleiten von Nachrichten aus der IoT Hub-Instanz an den Endpunkt.
• Konfigurieren Sie Nachrichtenerweiterungen, die an den neuen Endpunkt weitergeleitet werden.
• Führen Sie eine App aus, die ein IoT-Gerät simuliert, das Nachrichten an den Hub sendet.
• Zeigen Sie die Ergebnisse an, und stellen Sie sicher, dass die Nachrichtenanreicherungen auf die ausgewählten Nachrichten angewendet werden.

Voraussetzungen

• Sie benötigen ein Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

• Sie müssen das Tutorial: Senden von Gerätedaten an Azure Storage mit IoT Hub-Nachrichtenweiterleitung abgeschlossen haben und die Ressourcen aufbewahrt haben, die Sie dafür erstellt haben.

• Stellen Sie sicher, dass Port 8883 in Ihrer Firewall geöffnet ist. Für das Beispielgerät in diesem Tutorial wird das MQTT-Protokoll verwendet, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Azure portal

Für das Azure-Portal gibt es keine anderen Voraussetzungen.

Azure-Befehlszeilenschnittstelle

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

  • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

  • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Einen Container in Ihrem Speicherkonto erstellen

Im ersten Teil dieses Tutorials haben Sie ein Speicherkonto und einen Container für weitergeleitete Nachrichten erstellt. Jetzt sollten Sie einen zweiten Container für angereicherte Nachrichten erstellen.

Azure portal

1. Suchen Sie im Azure-Portal nach Speicherkonten.

2. Wählen Sie das zuvor von Ihnen erstellte Konto aus.

3. Wählen Sie im Speicherkontomenü im Abschnitt Datenspeicher die Option Container aus.

4. Wählen Sie Container aus, um einen neuen Container zu erstellen.

   

5. Nennen Sie den Container enriched, und wählen Sie Erstellen aus.

Azure-Befehlszeilenschnittstelle

Tipp

Viele der in diesem Tutorial verwendeten CLI-Befehle verwenden dieselben Parameter. Der Einfachheit halber werden lokale Variablen definiert, die nach Bedarf aufgerufen werden können. Achten Sie darauf, alle Befehle in derselben Sitzung auszuführen. Andernfalls müssen Sie die Variablen neu definieren.

Die Werte für diese Variablen sollten für dieselben Ressourcen gelten, die Sie im ersten Teil dieses Tutorials verwendet haben.

1. Definieren Sie die Variablen für Ihren IoT-Hub, Ihr Speicherkonto und Ihren Container.

   GROUP_NAME: Ersetzen Sie diesen Platzhalter durch den Namen der Ressourcengruppe, die Ihre IoT Hub-Instanz enthält.

   IOTHUB_NAME: Ersetzen Sie diesen Platzhalter durch den Namen Ihres IoT Hub-Instanz.

   DEVICE_ID: Ersetzen Sie diesen Platzhalter durch die ID Ihres Geräts.

   STORAGE_NAME: Ersetzen Sie diesen Platzhalter durch den Namen Ihres Speicherkontos.

   Für dieses Tutorials sollte der Wert für die containerName-Variable angereichert sein.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. Fügen Sie Ihrem Speicherkonto mit dem Befehl az storage container create einen Container hinzu.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Weiterleiten von Nachrichten an einen zweiten Endpunkt

Erstellen Sie einen zweiten Endpunkt und leiten Sie die erweiterten Nachrichten an.

Azure portal

1. Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.

2. Wählen Sie im Ressourcenmenü unter Hubeinstellungen die Einstellung Nachrichtenrouting und dann Hinzufügen aus.

   

3. Erstellen Sie auf der Registerkarte Endpunkt einen Speicherendpunkt, indem Sie die folgenden Informationen angeben:

   Parameter	Wert
   Endpunkttyp	Wählen Sie Speicher.
   Endpunktname	Geben Sie ContosoStorageEndpointEnriched ein.
   Azure Storage-Container	Wählen Sie Container auswählen. Folgen Sie den Anweisungen zum Auswählen des Speicherkontos und des Containers enriched, die Sie im vorhergehenden Abschnitt erstellt haben.
   Codieren	Wählen Sie JSON aus. Wenn dieses Feld ausgegraut ist, wird JSON in der Region Ihres Speicherkontos nicht unterstützt. Fahren Sie in diesem Fall mit der Standardeinstellung AVRO fort.

   

4. Übernehmen Sie bei den restlichen Parametern die Standardwerte, und wählen Sie Erstellen + Weiter aus.

5. Fahren Sie mit der Erstellung der neuen Route fort, da Sie nun den Speicherendpunkt hinzugefügt haben. Geben Sie für die neue Route folgende Informationen an:

   Parameter	Wert
   Name	ContosoStorageRouteEnriched
   Datenquelle	Vergewissern Sie sich, dass Telemetrienachrichten für Geräte in der Dropdownliste ausgewählt ist.
   Route aktivieren	Überprüfen Sie, ob dieses Feld auf enabled festgelegt ist.
   Routingabfrage	Geben Sie level="storage" als Abfragezeichenfolge ein.

   

6. Wählen Sie Erstellen + Anreicherungen hinzufügen aus.

Azure-Befehlszeilenschnittstelle

1. Konfigurieren Sie die Variablen für die Endpunkt- und Routebefehle, um die Werte ContosoStorageEndpointEnriched und ContosoStorageRouteEnriched zu verwenden.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Erstellen Sie mithilfe des Befehls az iot hub message-endpoint create einen benutzerdefinierten Endpunkt, der auf den Speichercontainer verweist, den Sie im vorherigen Abschnitt erstellt haben.

   az iot hub message-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Erstellen Sie mithilfe des Befehls az iot hub message-route create eine Route, die jede Nachricht, für die level=storage gilt, an den Endpunkt des Speichercontainers übergibt.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Hinzufügen von Nachrichtenanreicherung zum neuen Endpunkt

Erstellen Sie drei Nachrichtenanreicherungen, die an den angereicherten Speichercontainer weitergeleitet werden.

Azure portal

1. Fügen Sie auf der Registerkarte Anreicherung des Assistenten Route hinzufügen drei Nachrichtenanreicherungen für die Nachrichten hinzu, die an den Endpunkt für den Speichercontainer enriched geleitet werden.

   Fügen Sie diese Werte als Nachrichtenanreicherung für den Endpunkt „ContosoStorageEndpointEnriched“ hinzu:

   Name	Wert
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (setzt voraus, dass der Gerätezwilling über ein Standorttag verfügt)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Wenn Sie fertig sind, sollten Ihre Anreicherungen ähnlich wie in dieser Abbildung aussehen:

   

2. Wählen Sie Hinzufügen aus, um die Nachrichtenanreicherungen hinzuzufügen.

Azure-Befehlszeilenschnittstelle

Führen Sie drei Aufrufe des Befehls az iot hub message-enrichment create aus, um Nachrichtenanreicherungen zur zuvor erstellten Endpunktroute hinzuzufügen.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Sie verfügen jetzt über Nachrichtenanreicherungen, die für alle Nachrichten eingerichtet sind, die an den Endpunkt weitergeleitet werden, den Sie für angereicherte Nachrichten erstellt haben. Wenn Sie dem Gerätezwilling kein Standorttag hinzufügen möchten, können Sie zum Abschnitt Nachrichtenanreicherungen testen springen, um das Lernprogramm fortzusetzen.

Standort-Tag zum Gerätezwilling hinzufügen

Eine der auf Ihrem IoT-Hub konfigurierten Nachrichtenanreicherungen gibt einen Schlüssel für DeviceLocation an, dessen Wert durch den folgenden Gerätezwillingspfad bestimmt wird: $twin.tags.location. Wenn Ihr Gerätezwilling kein Standort-Tag hat, wird der Zwillingspfad, $twin.tags.location, als Zeichenfolge für den DeviceLocation-Schlüssel in den Nachrichtenanreicherungen eingefügt.

Führen Sie diese Schritte aus, um dem Gerätezwilling über das Portal ein Standort-Tag hinzuzufügen:

Azure portal

1. Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.

2. Wählen Sie im Navigationsmenü des IoT-Hubs Geräte und dann Ihr Gerät aus.

3. Wählen Sie oben auf der Geräteseite die Registerkarte Gerätezwilling aus, und fügen Sie die folgende Zeile direkt vor der schließenden geschweiften Klammer am unteren Rand des Gerätezwillings hinzu. Klicken Sie dann auf Speichern.

     , "tags": {"location": "Plant 43"}
   

   

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az iot hub device-twin update, um den Gerätezwilling mit einem neuen Tag-Schlüssel und Wert zu aktualisieren.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Tipp

Warten Sie etwa fünf Minuten, bevor Sie mit dem nächsten Abschnitt fortfahren. Es kann bis zu so lange dauern, bis Updates des Gerätezwillings in Nachrichtenanreicherungswerten wiedergegeben werden.

Weitere Informationen dazu, wie Gerätezwillingspfade mit Nachrichtenanreicherungen behandelt werden, finden Sie unter Einschränkungen für Nachrichtenanreicherungen. Wenn Sie mehr über Gerätezwillinge erfahren möchten, lesen Sie den Abschnitt Gerätezwillinge in IoT Hub verstehen und nutzen.

Testen von Nachrichtenanreicherungen

Nachdem Sie die Nachrichtenanreicherungen für den Endpunkt ContosoStorageEndpointEnriched konfiguriert haben, führen Sie die App „Simuliertes Gerät“ aus, um Nachrichten an den IoT-Hub zu senden. An diesem Punkt wurde das Nachrichtenrouting wie folgt eingerichtet:

• Nachrichten, die Sie im ersten Teil des Tutorials erstellt haben, werden nicht an den von Ihnen erstellten Speicherendpunkt weitergeleitet und werden dann im von Ihnen erstellten Speichercontainer gespeichert.

• Nachrichten, die an den Speicherendpunkt ContosoStorageEndpointEnriched weitergeleitet wurden, werden angereichert und im Speichercontainer angereichert gespeichert.

Wenn Sie die SimulationdDevice-Konsolenanwendung aus dem ersten Teil dieses Tutorials noch nicht ausführen, führen Sie sie erneut aus:

Tipp

Wenn Sie die Azure CLI-Schritte dieses Tutorials ausführen, sollten Sie den Beispielcode in einer separaten Sitzung ausführen. Auf diese Weise können Sie zulassen, dass der Beispielcode weiter ausgeführt wird, während Sie mit den restlichen CLI-Schritten fortfahren.

1. Navigieren Sie im Beispielordner zu dem Ordner /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Die Variablendefinitionen, die Sie aktualisiert haben, sollten noch gültig sein, aber wenn nicht, bearbeiten Sie sie in der Program.cs-Datei:

   1. Suchen Sie die Variablendefinitionen oben in der Program-Klasse. Aktualisieren Sie folgende Variablen mit Ihren eigenen Informationen:

      • s_myDeviceId: Die Geräte-ID, die Sie beim Registrieren des Geräts zugewiesen haben.
      • s_iotHubUri: Der Hostname Ihrer IoT Hub-Instanz im Format IOTHUB_NAME.azure-devices.net
      • s_deviceKey: Der Primärschlüssel des Geräts, der in den Geräteidentitätsinformationen gefunden wurde.

   2. Speichern und schließen Sie die Datei.

3. Führen Sie den Beispielcode aus:

   dotnet run
   

Nach dem Verlassen der Konsolenanwendung, die für einige Minuten ausgeführt werden soll, zeigen Sie die Daten an:

1. Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto.

2. Wählen Sie dann im Navigationsmenü den Speicherbrowser aus. Wählen Sie Blob-Container aus, um die beiden Container anzuzeigen, die Sie im Laufe dieser Lernprogramme erstellt haben.

   

Den Nachrichten im Container enriched wurden die Nachrichtenanreicherungen hinzugefügt. Die Nachrichten im Container, den Sie zuvor erstellt haben, enthalten die Rohnachrichten ohne Anreicherungen. Führen Sie einen Drilldown in einen der angereicherten Container bis zum unteren Ende aus und öffnen Sie dann die aktuellste Nachrichtendatei. Führen Sie dann denselben Vorgang für den anderen Container aus, um zu überprüfen, ob einer angereichert ist und der andere nicht.

Bei angereicherten Nachrichten sollten Sie "myIotHub" mit dem Hubnamen, dem Speicherort und der Kunden-ID sehen, wie im Folgenden zu sehen:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Bereinigen von Ressourcen

Wenn Sie alle für dieses Tutorial erstellten Ressourcen entfernen möchten, löschen Sie die Ressourcengruppe. Diese Aktion löscht alle in der Gruppe enthaltenen Ressourcen. Wenn Sie nicht die gesamte Ressourcengruppe löschen möchten, können Sie einzelne Ressourcen darin für die Löschung auswählen.

Azure portal

1. Navigieren Sie im Azure-Portal zu der Ressourcengruppe, die die IoT Hub-Instanz und das Speicherkonto für dieses Tutorial enthält.
2. Prüfen Sie alle Ressourcen in der Ressourcengruppe, um zu entscheiden, welche Ressourcen Sie entfernen möchten.
   • Wenn Sie alle Ressourcen löschen möchten, klicken Sie auf Ressourcengruppe löschen.
   • Wenn Sie nur bestimmte Ressourcen löschen möchten, aktivieren Sie die Kontrollkästchen neben den jeweiligen Ressourcennamen, um die zu löschenden Ressourcen auszuwählen. Wählen Sie anschließend die Option Löschen.

Azure-Befehlszeilenschnittstelle

1. Führen Sie den Befehl az resource list aus, um alle Ressourcen Ihrer Ressourcengruppe aufzulisten.

   az resource list --resource-group $resourceGroup --output table
   

2. Prüfen Sie alle Ressourcen in der Ressourcengruppe, um zu entscheiden, welche Ressourcen Sie entfernen möchten.

   • Wenn Sie alle Ressourcen löschen möchten, führen Sie den Befehl az group delete aus.

     az group delete --name $resourceGroup
     

   • Wenn Sie nur bestimmte Ressourcen löschen möchten, führen Sie den Befehl az resource delete aus. Beispiel:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Nächste Schritte

In diesem Tutorial haben Sie Nachrichtenanreicherungen für IoT Hub-Nachrichten konfiguriert und getestet, während sie an einen Endpunkt weitergeleitet werden.

Weitere Informationen zu Nachrichtenanreicherungen finden Sie unter Übersicht über Nachrichtenanreicherungen.

Weitere Informationen zu IoT Hub finden Sie im nächsten Tutorial.

Tutorial: Einrichten und Verwenden von Metriken und Protokollen mit einem IoT-Hub