Tutorial: Senden von Gerätedaten an Azure Storage über IoT Hub-Nachrichtenrouting

Verwenden Sie Nachrichtenrouting in Azure IoT Hub, um Telemetriedaten von Ihren IoT-Geräten an Azure-Dienste wie Blob-Speicher, Service Bus-Warteschlangen, Service Bus-Themen und Event Hubs zu senden. Jede IoT Hub-Instanz verfügt über einen standardmäßig integrierten Endpunkt, der mit Event Hubs kompatibel ist. Sie können auch benutzerdefinierte Endpunkte erstellen und Nachrichten an andere Azure-Dienste weiterleiten, indem Sie Routingabfragen definieren. Jede Nachricht, die bei einer IoT Hub-Instanz ankommt, wird an alle Endpunkte weitergeleitet, mit deren Routingabfragen sie übereinstimmt. Wenn eine Nachricht nicht mit einer der definierten Routingabfragen übereinstimmt, wird sie an den Standardendpunkt geleitet.

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

• Erstellen einer IoT Hub-Instanz und Senden von Gerätenachrichten an diese
• Erstellen Sie ein Speicherkonto.
• Erstellen eines benutzerdefinierten Endpunkts für das Speicherkonto und Weiterleiten von Nachrichten aus der IoT Hub-Instanz an den Endpunkt
• Anzeigen von Gerätenachrichten im Speicherkontoblob

Voraussetzungen

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

• Ein IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.

• In diesem Tutorial wird Beispielcode aus dem Azure IoT-SDK für C# verwendet.

  • Laden Sie das SDK-Repository auf Ihren Entwicklungscomputer herunter, oder klonen Sie es.
  • Auf Ihrem Entwicklungscomputer muss das .NET Core SDK 3.0.0 oder höher installiert sein. Überprüfen Sie Ihre Version, indem Sie dotnet --version ausführen und, falls erforderlich, .NET herunterladen.

• Stellen Sie sicher, dass Port 8883 in Ihrer Firewall geöffnet ist. Für das Beispiel 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).

• Installieren Sie optional den Azure IoT-Explorer. Dieses Tool hilft Ihnen, die Nachrichten zu beobachten, wenn sie an Ihrer IoT Hub-Instanz ankommen. In diesem Artikel wird Azure IoT Explorer verwendet.

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.

Registrieren eines Geräts und Senden von Nachrichten an IoT Hub

Registrieren Sie ein Gerät bei Ihrer IoT Hub-Instanz.

Azure portal

1. Melden Sie sich beim Azure-Portal an, und navigieren Sie zu Ihrem IoT Hub.

2. Wählen Sie im Abschnitt Geräteverwaltung des Menüs die Option Geräte aus.

3. Klicken Sie auf Gerät hinzufügen.

   

4. Geben Sie eine Geräte-ID an, und klicken Sie auf Speichern.

5. Das neue Gerät sollte sich jetzt in der Liste der Geräte aufgeführt sein. Falls nicht, aktualisieren Sie die Seite. Wählen Sie die Geräte-ID aus, um die Gerätedetailseite zu öffnen.

6. Kopieren Sie einen der Geräteschlüssel, und speichern Sie ihn. Sie werden mit diesem Wert später den Beispielcode konfigurieren, der Telemetrienachrichten von simulierten Geräten generiert.

   

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.

1. Definieren Sie Variablen für Ihre IoT Hub-Instanz und Ihr Gerät.

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

   DEVICE_NAME: Ersetzen Sie diesen Platzhalter durch einen beliebigen Namen, den Sie in diesem Tutorial für Ihr Gerät verwenden möchten.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Führen Sie in der CLI-Shell den Befehl az iot hub device-identity create aus. Dieser Befehl erstellt die Geräteidentität.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. Kopieren Sie den Wert von primaryKey ohne die umgebenden Anführungszeichen aus der Ausgabe von „device-identity“, und speichern Sie ihn. Sie werden mit diesem Wert später den Beispielcode konfigurieren, der Telemetrienachrichten von simulierten Geräten generiert.

Da Sie nun über eine Geräte-ID und einen Schlüssel verfügen, können Sie mithilfe des Beispielcodes Gerätetelemetrienachrichten an IoT Hub senden.

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. Wenn Sie das nicht bereits im Rahmen der oben genannten Voraussetzungen erledigt haben, laden Sie jetzt das Repository „Azure IoT-SDK für C#“ von GitHub herunter, oder klonen Sie es.

2. Navigieren Sie aus dem Ordner, in den Sie das SDK heruntergeladen oder geklont haben, zum Ordner azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample.

3. Installieren Sie, wie in der Datei HubRoutingSample.csproj angegeben, das C#-SDK für Azure IoT sowie alle erforderlichen Abhängigkeiten:

   dotnet restore
   

4. Öffnen Sie die Datei Parameters.cs in einem Editor Ihrer Wahl. Diese Datei enthält die vom Beispiel unterstützten Parameter. Beim Ausführen des Beispiels wird nur der PrimaryConnectionString-Parameter in diesem Artikel verwendet. Sehen Sie sich den Code in dieser Datei an. Es sind keine Änderungen erforderlich.

5. Erstellen Sie den Code, und führen Sie ihn mithilfe des folgenden Befehls aus:

   Ersetzen Sie <myDevicePrimaryConnectionString> durch die primäre Verbindungszeichenfolge von Ihrem Gerät in Ihrem IoT-Hub.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Wenn Nachrichten an Ihre IoT Hub-Instanz gesendet werden, sollten diese in der Ausgabe ausgegeben werden. Behalten Sie die Ausführung dieses Programms für die Dauer des Tutorials bei.

Konfigurieren des IoT-Explorers zum Anzeigen von Nachrichten

Konfigurieren Sie den IoT-Explorer für die Verbindungsherstellung mit Ihrer IoT Hub-Instanz und das Lesen von Nachrichten, sobald diese am integrierten Endpunkt ankommen.

Rufen Sie zunächst die Verbindungszeichenfolge für Ihre IoT Hub-Instanz ab.

Azure portal

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

2. Klicken Sie im Abschnitt Sicherheitseinstellungen des Menüs auf Richtlinien für gemeinsamen Zugriff.

3. Wählen Sie die Richtlinie iothubowner aus.

   

4. Kopieren Sie den Wert unter Primäre Verbindungszeichenfolge.

   

Azure-Befehlszeilenschnittstelle

1. Führen Sie den Befehl az iot hub connection-string show aus.

   az iot hub connection-string show --hub-name $hubName
   

2. Kopieren Sie die Verbindungszeichenfolge ohne die umgebenden Anführungszeichen.

Nun werden Sie den IoT-Explorer dieser Verbindungszeichenfolge für Ihre IoT Hub-Instanz konfigurieren.

1. Öffnen Sie den IoT-Explorer auf Ihrem Entwicklungscomputer.

2. Wählen Sie Verbindung hinzufügen aus.

   

3. Fügen Sie die Verbindungszeichenfolge Ihrer Hub-Instanz in das Textfeld ein.

4. Wählen Sie Speichern aus.

5. Sobald Sie eine Verbindung mit Ihrer IoT Hub-Instanz herstellen, sollten Ihnen eine Geräteliste angezeigt werden. Wählen Sie die Geräte-ID aus, die Sie für dieses Tutorial erstellt haben.

6. Wählen Sie Telemetrie aus.

7. Während Ihr Gerät weiterhin ausgeführt wird, wählen Sie Start aus. Wenn Ihr Gerät nicht ausgeführt wird, wird keine Telemetrie angezeigt.

   

8. Ihnen sollten die Nachrichten angezeigt werden, die von Ihrem Gerät aus ankommen, wobei die neueste ganz oben stehen sollte.

   

   Sehen Sie sich die eingehenden Nachrichten einige Momente lang an, um zu prüfen, ob drei verschiedene Arten von Nachrichten angezeigt werden: „normal“, „storage“ (Speicher) und „critical“ (kritisch). Nachdem sie angezeigt wurde, können Sie Ihr Gerät beenden.

Diese Nachrichten kommen alle am standardmäßig integrierten Endpunkt für Ihre IoT Hub-Instanz an. In den nächsten Abschnitten erstellen Sie einen benutzerdefinierten Endpunkt und leiten einige dieser Nachrichten basierend auf den Nachrichteneigenschaften an den Speicher weiter. Diese Nachrichten werden nicht mehr im IoT-Explorer angezeigt, da Nachrichten nur am integrierten Endpunkt ankommen, wenn sie mit keiner anderen Route in der IoT Hub-Instanz übereinstimmen.

Einrichten der Nachrichtenweiterleitung

Sie leiten Nachrichten basierend auf Eigenschaften, die vom simulierten Gerät an die Nachricht angefügt werden, an verschiedene Ressourcen weiter. Nachrichten ohne benutzerdefinierte Weiterleitung, werden an den Standardendpunkt gesendet (Nachrichten/Ereignisse).

Die Beispiel-App in diesem Tutorial weist jeder Nachricht, die sie an die IoT Hub-Instanz sendet, eine level-Eigenschaft zu. Jede Nachricht wird zufällig der Ebene (engl.: level) normal, storage oder critical zugewiesen.

Als Erstes muss der Endpunkt eingerichtet werden, an den die Daten weitergeleitet werden. Danach wird die Nachrichtenroute eingerichtet, die diesen Endpunkt verwendet. Nach Einrichtung des Routings können Sie die Endpunkte und Nachrichtenrouten im Portal anzeigen.

Speicherkonto erstellen

Erstellen Sie ein Azure Storage-Konto und innerhalb dieses Kontos einen Container, in dem die Gerätenachrichten an das Konto weitergeleiteten Gerätenachrichten aufbewahrt werden.

Azure portal

1. Suchen Sie im Azure-Portal nach Speicherkonten.

2. Klicken Sie auf Erstellen.

3. Geben Sie die folgenden Werte für Ihr Speicherkonto an:

   Parameter	Wert
   Abonnement	Wählen Sie dasselbe Abonnement aus, das Ihre IoT Hub-Instanz enthält.
   Ressourcengruppe	Wählen Sie dieselbe Ressourcengruppe aus, die Ihre IoT Hub-Instanz enthält.
   Speicherkontoname	Geben Sie einen global eindeutigen Namen für Ihr Speicherkonto an.
   Leistung	Übernehmen Sie den Standardwert Standard.

   

4. Sie können alle anderen Standardwerte akzeptieren, indem Sie auf Überprüfen und erstellen klicken.

5. Wenn die Überprüfung abgeschlossen ist, wählen Sie Erstellen aus.

6. Wenn Ihre Bereitstellung abgeschlossen ist, wählen Sie Go to resource (Zu Ressource wechseln) aus.

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

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

   

9. Geben Sie einen Namen für Ihren Container ein, und klicken Sie auf Erstellen.

Azure-Befehlszeilenschnittstelle

1. Definieren Sie die Variablen für Ihr Speicherkonto und Ihren Container.

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

   STORAGE_NAME: Ersetzen Sie diesen Platzhalter durch einen Namen Ihres Speicherkontos. Namen von Speicherkonten müssen klein geschrieben und global eindeutig sein.

   CONTAINER_NAME: Ersetzen Sie diesen Platzhalter durch einen Namen Ihres Containers.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Erstellen Sie mit dem Befehl az storage account create ein allgemeines v2-Standardspeicherkonto.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. 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 an ein Speicherkonto

Richten Sie jetzt die Weiterleitung für das Speicherkonto ein. In diesem Abschnitt definieren Sie einen neuen Endpunkt, der auf das von Ihnen erstellte Speicherkonto verweist. Erstellen Sie dann eine Route, die nach Nachrichten filtert, in denen die level-Eigenschaft auf storage festgelegt ist, und leiten Sie die Nachrichten an den Speicherendpunkt weiter.

Hinweis

Die Daten können entweder im Apache Avro-Format (Standardeinstellung) oder im JSON-Format in den Blobspeicher geschrieben werden.

Das Codierungsformat kann nur beim Konfigurieren des Blob Storage-Endpunkt festgelegt werden. Für bereits eingerichtete Endpunkte kann das Format nicht mehr geändert werden. Bei Verwendung der JSON-Codierung müssen Sie in den Nachrichtensystemeigenschaften den Inhaltstyp (contentType) auf „JSON“ und die Inhaltscodierung (contentEncoding) auf „UTF-8“ festlegen.

Ausführlichere Informationen zur Verwendung eines Blob Storage-Endpunkts finden Sie unter Leitfaden zum Weiterleiten an den Speicher.

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 einen eindeutigen Namen für diesen Endpunkt an.
   Azure Storage-Container	Wählen Sie Container auswählen. Folgen Sie den Anweisungen zum Auswählen des Speicherkontos und Containers, 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. Geben Sie auf der Registerkarte Route die folgenden Informationen zum Erstellen einer Route an, die auf den von Ihnen erstellten Speicherendpunkt verweist:

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

   

6. Wählen Sie Anreicherungen erstellen + überspringen aus.

Azure-Befehlszeilenschnittstelle

1. Konfigurieren Sie die Variablen, die Sie für den Endpunkt und die Routenbefehle benötigen.

   ENDPOINT_NAME: Geben Sie einen Namen für den Endpunkt an, der Ihren Speichercontainer darstellt.

   ROUTE_NAME: Geben Sie einen Namen für die Route an, die Nachrichten für den Speicherendpunkt filtert.

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

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

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

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

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

Anzeigen weitergeleiteter Nachrichten

Sobald die Route in IoT Hub erstellt und aktiviert wurde, werden umgehend Nachrichten darüber weitergeleitet, die die Routenabfragebedingung bzgl. des Speicherendpunkts erfüllen.

Überwachen des integrierten Endpunkts mit dem IoT-Explorer

Kehren Sie zur IoT-Explorer-Sitzung auf Ihrem Entwicklungscomputer zurück. Denken Sie daran, dass der IoT-Explorer den integrierten Endpunkt Ihrer IoT Hub-Instanz überwacht. Dies bedeutet, dass Ihnen jetzt nur die Nachrichten angezeigt werden sollten, die nicht von Ihrer erstellten benutzerdefinierten Route weitergeleitet werden.

Starten Sie das Beispiel erneut, indem Sie den Code ausführen. Beobachten Sie die eingehenden Nachrichten für einige Momente. Sie sollten nur Nachrichten sehen, für die level auf normal bzw. critical festgelegt ist.

Anzeigen von Nachrichten im Speichercontainer

Stellen Sie sicher, dass die Nachrichten im Speichercontainer ankommen.

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

2. Klicken Sie im Abschnitt Datenspeicher des Menüs auf Container.

3. Wählen Sie den Container aus, den Sie für dieses Tutorial erstellt haben.

4. Es sollte ein Ordner vorhanden sein, der den Namen Ihrer IoT Hub-Instanz trägt. Führen Sie einen Drilldown durch die Dateistruktur aus, bis Sie zu einer JSON-Datei gelangen.

   

5. Wählen Sie die JSON-Datei aus, und wählen Sie dann Herunterladen aus, um die JSON-Datei herunterzuladen. Überprüfen Sie, dass die Datei Nachrichten von Ihrem Gerät enthält, deren level-Eigenschaft auf storage festgelegt ist.

6. Beenden Sie die Ausführung des Beispiels.

Bereinigen von Ressourcen

Wenn Sie alle in diesem Tutorial verwendeten Azure-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, suchen und löschen Sie die einzelnen Ressourcen über das Azure-Portal.

Wenn Sie mit dem nächsten Tutorial weitermachen möchten, behalten Sie die hier erstellten Ressourcen bei.

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 gelernt, wie Sie einen benutzerdefinierten Endpunkt für eine Azure-Ressource erstellen und dann eine Route zum Senden von Gerätenachrichten an diesen Endpunkt erstellen. Fahren Sie mit dem nächsten Tutorial fort, um zu erfahren, wie Sie Nachrichten mit zusätzlichen Daten anreichern, um die spätere Verarbeitung zu vereinfachen.

Verwenden von Azure IoT Hub-Nachrichtenanreicherungen