Erstellen und Löschen von Routen und Endpunkten mithilfe der Azure-Befehlszeilenschnittstelle (Azure CLI)

In diesem Artikel erfahren Sie, wie Sie Azure IoT Hub Routen und -Endpunkte mithilfe der Azure CLI verwalten. Hier erfahren Sie, wie Sie mithilfe der Azure CLI Routen und Endpunkte für Azure Event Hubs, Azure Service Bus-Warteschlangen und -Themen, Azure Storage und Cosmos DB erstellen.

Weitere Informationen zur Funktionsweise des Routings in IoT Hub finden Sie unter Verwenden des IoT Hub-Nachrichtenroutings zum Senden von D2C-Nachrichten an verschiedene Endpunkte. Informationen zum Einrichten einer Route, die Nachrichten an den Speicher sendet, mit anschließendem Testen auf einem simulierten Gerät finden Sie im Tutorial: Senden von Gerätedaten an Azure Storage über IoT Hub-Nachrichtenrouting.

Voraussetzungen

Bei den in diesem Artikel beschriebenen Verfahren werden die folgenden Ressourcen verwendet:

• Die Azure CLI
• Ein IoT Hub
• Ein Endpunktdienst in Azure

Azure CLI

In diesem Artikel wird die Azure-Befehlszeilenschnittstelle (Azure CLI) zum Arbeiten mit IoT Hub und anderen Azure-Diensten verwendet. Sie können auswählen, wie Sie auf die Azure CLI zugreifen möchten:

• 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.

IoT Hub

Sie benötigen einen IoT-Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs mit der Azure-Befehlszeilenschnittstelle ausführen.

Endpunktdienst

Sie benötigen mindestens einen weiteren Azure-Dienst, der als Endpunkt für die Route verwendet werden soll. Der Endpunkt empfängt Gerätenachrichten und Ereignisprotokolle.

Entscheiden Sie, welchen Azure-Dienst Sie als Endpunkt zum Empfangen von weitergeleiteten Geräte- und Ereignisdaten verwenden möchten: einen Event Hub, eine Dienstwarteschlange oder ein Dienstthema, ein Speicherkonto oder aber einen Cosmos DB-Container. Führen Sie für den Dienst, den Sie verwenden möchten, die Schritte zum Erstellen eines Endpunktdiensts aus.

Event Hubs

1. Erstellen Sie einen Event Hubs-Namespace und einen Event Hub. Weitere Informationen finden Sie im Schnellstart: Erstellen eines Event Hubs mithilfe der Azure CLI.

2. Erstellen Sie eine Autorisierungsregel, mit der eine IoT Hub-Berechtigung zum Senden von Daten an den Event Hub erteilt werden soll.

   Tipp

   Der Wert RootManageSharedAccessKey des name-Parameters ist der Standardname, der Ansprüche für Verwalten, Senden, Lauschen (Zugriff) zulässt. Wenn Sie die Ansprüche einschränken möchten, geben Sie dem name-Parameter einen eigenen eindeutigen Namen, und fügen Sie das --rights-Flag ein, gefolgt von einem der Ansprüche. Beispiel: --name my-name --rights Send.

   az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
   

   Weitere Informationen finden Sie unter Autorisieren des Zugriffs auf Azure Event Hubs.

Service Bus-Warteschlange

1. Erstellen Sie einen Service Bus-Namespace und eine Service Bus-Warteschlange. Weitere Informationen finden Sie unter Verwenden der Azure CLI zum Erstellen eines Service Bus-Namespace und einer Warteschlange.

2. Erstellen Sie eine Autorisierungsregel, die eine IoT Hub-Berechtigung zum Senden von Daten an die Warteschlange erteilen soll. Verwenden Sie bei name einen eindeutigen Wert für Ihre Autorisierungsregel.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   Weitere Optionen für Autorisierungsregeln finden Sie unter az servicebus queue authorization-rule create.

Service Bus-Topic

Erstellen Sie einen Namespace, ein Thema und ein Abonnement für Service Bus. Weitere Informationen finden Sie unter Erstellen eines Service Bus-Themas und Abonnements dieses Themas über die Azure CLI.

Azure Storage (in englischer Sprache)

1. Erstellen Sie ein Speicherkonto. Weitere Informationen finden Sie unter Erstellen eines Speicherkontos.

2. Erstellen Sie einen Container in Ihrem Speicherkonto. Weitere Informationen finden Sie unter Verwalten von Blobcontainern mithilfe der Azure CLI.

Cosmos DB

Erstellen Sie ein Cosmos DB-Konto für die SQL-API und einen Cosmos DB-Container. Weitere Informationen finden Sie unter Erstellen eines Azure Cosmos DB for NoSQL-Kontos.

Erstellen eines Endpunkts

Alle IoT Hub-Routen verweisen auf einen Endpunkt, der die weitergeleiteten Geräte- und Ereignisdaten empfangen wird. Mehrere Routen können auf denselben Endpunkt verweisen. IoT Hub unterstützt zurzeit Endpunkte für Event Hubs, Service Bus-Warteschlangen oder -Themen, Storage und Cosmos DB. In Ihrem Abonnement muss eine Instanz des für Ihren Endpunkt verwendeten Dienstes vorhanden sein, bevor Sie den Endpunkt erstellen.

Hinweis

In diesem Artikel wird die Befehlsgruppe az iot hub message-endpoint verwendet, die in Version 0.19.0 der Azure-IoT-Erweiterung für die Azure CLI eingeführt wurde. In früheren Versionen der Azure-IoT-Erweiterung wurde die Befehlsgruppe az iot hub routing-endpoint verwendet, die ähnlich ist und weiterhin unterstützt wird, das Erstellen von Cosmos DB-Endpunkten aber nicht unterstützt.

Verwenden Sie den folgenden Befehl zum Aktualisieren auf die neueste Version der Azure-IoT-Erweiterung:

az extension update --name azure-iot

Event Hubs

Verwenden Sie zum Erstellen eines Event Hubs-Endpunkts die Autorisierungsregel, die Sie in den Voraussetzungen erstellt haben.

1. Verwenden Sie den Befehl az eventhubs eventhub authorization-rule keys list zum Auflisten Ihrer Autorisierungsregel. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   eventhub_group	Ressourcengruppe des Event Hubs.
   eventhub_namespace	Der Name des Event Hubs-Namespace.
   eventhub_name	Name des Event Hubs.
   rule_name	Der Name der Autorisierungsregel für den Event Hub. Wenn Sie das Beispiel in den Voraussetzungen kopiert haben, lautet dieser Name RootManageSharedAccessKey.

   az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}
   

2. Kopieren Sie die Verbindungszeichenfolge für Ihren Event Hub aus der Ausgabe.

3. Verwenden Sie den Befehl az iot hub message-endpoint create eventhub zum Erstellen Ihres benutzerdefinierten Endpunkts. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem dieser Endpunkt erstellt wird.
   endpoint_name	Ein eindeutiger Name für den neuen Endpunkt.
   eventhub_subscription	Abonnement-ID des Event Hubs. Dieses Argument kann weggelassen werden, wenn sich der Event Hub in demselben Abonnement wie der IoT-Hub befindet.
   eventhub_group	Ressourcengruppe des Event Hubs. Dieses Argument kann weggelassen werden, wenn sich der Event Hub in derselben Ressourcengruppe wie der IoT-Hub befindet.
   eventhub_connection_string	Die Verbindungszeichenfolge, die Sie aus der Autorisierungsregel für den Event Hub kopiert haben.

   az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}
   

Service Bus-Warteschlange

Verwenden Sie zum Erstellen eines Endpunkts für die Service Bus-Warteschlange die Autorisierungsregel, die Sie in den Voraussetzungen erstellt haben.

1. Verwenden Sie den Befehl az servicebus queue authorization-rule keys list zum Abrufen der Verbindungszeichenfolge für Ihre Service Bus-Warteschlange. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   queue_group	Ressourcengruppe der Service Bus-Warteschlange.
   queue_namespace	Name des Namespaces für die Service Bus-Warteschlange.
   queue_name	Name der Warteschlange.
   rule_name	Der Name der Autorisierungsregel für die Warteschlange. Wenn Sie das Beispiel in den Voraussetzungen kopiert haben, lautet dieser Name my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. Kopieren Sie die Verbindungszeichenfolge für Ihre Service Bus-Warteschlange aus der Ausgabe.

3. Verwenden Sie den Befehl az iot hub message-endpoint create servicebus-queue zum Erstellen Ihres benutzerdefinierten Endpunkts. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem dieser Endpunkt erstellt wird.
   endpoint_name	Ein eindeutiger Name für den neuen Endpunkt.
   queue_connection_string	Die Verbindungszeichenfolge, die Sie aus der Autorisierungsregel für die Service Bus-Warteschlange kopiert haben.
   queue_subscription	Abonnement-ID der Service Bus-Warteschlange. Dieses Argument kann weggelassen werden, wenn sich die Warteschlange in demselben Abonnement wie der IoT-Hub befindet.
   queue_group	Ressourcengruppe der Service Bus-Warteschlange. Dieses Argument kann weggelassen werden, wenn sich die Warteschlange in derselben Ressourcengruppe wie der IoT-Hub befindet.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

Service Bus-Topic

1. Verwenden Sie den Befehl az servicebus topic authorization-rule keys list zum Abrufen der Verbindungszeichenfolge für Ihr Service Bus-Thema. Der Standardname Ihrer Autorisierungsregel, die einen neuen Namespace enthält, lautet RootManageSharedAccessKey. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   topic_group	Ressourcengruppe des Service Bus-Themas.
   topic_namespace	Name des Namespaces für das Service Bus-Thema.
   topic_name	Name des Themas.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. Kopieren Sie die Verbindungszeichenfolge für Ihr Service Bus-Thema aus der Ausgabe.

3. Verwenden Sie den Befehl az iot hub message-endpoint create servicebus-topic zum Erstellen Ihres benutzerdefinierten Endpunkts. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem dieser Endpunkt erstellt wird.
   endpoint_name	Ein eindeutiger Name für den neuen Endpunkt.
   topic_connection_string	Die Verbindungszeichenfolge, die Sie aus der Autorisierungsregel für das Service Bus-Thema kopiert haben.
   topic_subscription	Abonnement-ID des Service Bus-Themas. Dieses Argument kann weggelassen werden, wenn sich das Thema in demselben Abonnement wie der IoT-Hub befindet.
   topic_group	Ressourcengruppe des Service Bus-Themas. Dieses Argument kann weggelassen werden, wenn sich das Thema in derselben Ressourcengruppe wie der IoT-Hub befindet.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

Azure Storage (in englischer Sprache)

1. Verwenden Sie den Befehl az storage account show-connection-string, um die Verbindungszeichenfolge zum Erstellen eines Endpunkts aus Ihrer Azure Storage-Ressource abzurufen. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   storage_group	Ressourcengruppe des Speicherkontos.
   storage_name	Name des Speicherkontos.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. Kopieren Sie die Verbindungszeichenfolge für Ihr Speicherkonto aus der Ausgabe.

3. Verwenden Sie den Befehl az iot hub message-endpoint create storage-container zum Erstellen eines neuen Azure Storage-Endpunkts. Verwenden Sie bei allen anderen Parametern Werte für Ihr Szenario. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem dieser Endpunkt erstellt wird.
   endpoint_name	Ein eindeutiger Name für den neuen Endpunkt.
   storage_connection_string	Die Verbindungszeichenfolge, die Sie aus dem Speicherkontobefehl kopiert haben.
   container_name	Der Name des Containers in Ihrem Speicherkonto, an den die Daten gesendet werden.
   storage_subscription	Abonnement-ID des Service Bus-Speichers. Dieses Argument kann weggelassen werden, wenn sich der Speicher in demselben Abonnement wie der IoT-Hub befindet.
   storage_group	Ressourcengruppe des Service Bus-Speichers. Dieses Argument kann weggelassen werden, wenn sich das Thema in derselben Ressourcengruppe wie der IoT-Hub befindet.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. Verwenden Sie den Befehl az cosmosdb keys list zum Abrufen der Verbindungszeichenfolge aus Ihrem Cosmos DB-Datenbankkonto.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. Kopieren Sie Ihre Cosmos DB-Verbindungszeichenfolge aus der Ausgabe.

3. Verwenden Sie den Befehl az iot hub message-endpoint create cosmosdb-container zum Erstellen Ihres benutzerdefinierten Endpunkts. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem dieser Endpunkt erstellt wird.
   endpoint_name	Ein eindeutiger Name für den neuen Endpunkt.
   cosmosdb_connection_string	Die Verbindungszeichenfolge, die Sie aus dem Cosmos DB-Kontobefehl kopiert haben.
   container_name	Der Name des Containers in Ihrem Cosmos DB-Konto, an den die Daten gesendet werden.
   database_name	Der Name der Datenbank in Ihrem Cosmos DB-Konto, an die die Daten gesendet werden.
   cosmosdb_subscription	Abonnement-ID des Cosmos DB-Datenbankkontos. Dieses Argument kann weggelassen werden, wenn sich die Datenbank in demselben Abonnement wie der IoT-Hub befindet.
   cosmosdb_group	Ressourcengruppe des Cosmos DB-Datenbankkontos. Dieses Argument kann weggelassen werden, wenn sich die Datenbank in derselben Ressourcengruppe wie der IoT-Hub befindet.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   Hinweis

   Wenn Sie verwaltete Identitäten statt der Verbindungszeichenfolge verwenden, authentifizieren Sie Ihre Identität beim Cosmos DB-Konto mit dem Befehl az cosmosdb sql role assignment create.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

Einen Endpunkt löschen

Wenn Sie einen Endpunkt aus Ihrem IoT-Hub löschen möchten, verwenden Sie den Befehl az iot hub message-endpoint delete. Mit diesem Befehl können Sie einen einzelnen Endpunkt, alle Endpunkte eines einzelnen Typs oder alle Endpunkte aus einem Hub löschen.

Mit dem folgenden Befehl beispielsweise werden alle Endpunkte in einem IoT-Hub gelöscht, die auf Speicherressourcen verweisen:

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

Erstellen einer IoT Hub-Route

In IoT Hub können Sie eine Route erstellen, um Nachrichten zu senden oder Ereignisse zu erfassen. Bei jeder Route gibt es eine Datenquelle und einen Endpunkt. Die Datenquelle ist der Ursprung von Nachrichten oder Ereignisprotokollen. Der Endpunkt ist der Ort, an dem die Nachrichten oder Ereignisprotokolle enden. Sie wählen Speicherorte für die Datenquelle und den Endpunkt aus, wenn Sie in Ihrem IoT Hub eine neue Route erstellen. Optional können Sie Abfragen zu Nachrichtenrouten hinzufügen, um Nachrichten oder Ereignisse zu filtern, bevor sie zum Endpunkt gelangen.

Hinweis

In diesem Artikel wird die Befehlsgruppe az iot hub message-route verwendet, die in Version 0.19.0 der Azure-IoT-Erweiterung für die Azure CLI eingeführt wurde. In früheren Versionen der Azure-IoT-Erweiterung wurde die Befehlsgruppe az iot hub route verwendet, die ähnlich ist und weiterhin unterstützt wird.

Verwenden Sie den folgenden Befehl zum Aktualisieren auf die neueste Version der Azure-IoT-Erweiterung:

az extension update --name azure-iot

1. Verwenden Sie den Befehl az iot hub message-route create zum Erstellen einer neuen IoT Hub-Route mithilfe dieses Endpunkts. Geben Sie die folgenden Werte für die Platzhalterparameter an:

   parameter	value
   iothub_name	Der Name des IoT-Hubs, in dem diese Route erstellt wird.
   route_name	Ein eindeutiger Name für die neue Route.
   endpoint_name	Der Name des Endpunkts, an den die Route Daten senden wird.
   data_source	Die Quelle der Route. Zulässige Werte sind: deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid oder twinchangeevents.

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. Zur Bestätigung, dass sich die neue Route in Ihrem IoT-Hub befindet, verwenden Sie den Befehl az iot hub message-route list zum Anzeigen aller Routen in Ihrem IoT-Hub:

   az iot hub message-route list --hub-name {iothub_name}
   

   In der Azure CLI sollte eine Antwort angezeigt werden, die ähnlich wie in diesem Beispiel lautet:

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

Aktualisieren einer IoT Hub-Route

Nachdem eine Route erstellt wurde, können Sie einige Eigenschaften davon aktualisieren. Sie können die Quelle, den Endpunkt, die Bedingung oder den aktivierten Zustand einer vorhandenen Route ändern.

Verwenden Sie den Befehl az iot hub message-route show zum Anzeigen der Details einer Route.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

Verwenden Sie den Befehl az iot hub message-route update zum Aktualisieren der Eigenschaften einer Route. Mit dem folgenden Befehl beispielsweise wird die Quelle der Route aktualisiert.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

Löschen einer IoT Hub-Route

Verwenden Sie den Befehl az iot hub message-route delete zum Löschen einer Route aus Ihrem IoT-Hub.

Durch das Löschen einer Route wird deren Endpunkt nicht gelöscht, weil andere Routen möglicherweise auf denselben Endpunkt verweisen. Wenn Sie einen Endpunkt löschen möchten, können Sie das unabhängig vom Löschen einer Route tun.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

Verwalten der Fallbackroute

Die Fallbackroute sendet alle Nachrichten aus der Quelle devicemessages, die die Abfragebedingungen für keine der vorhandenen Routen erfüllen, an den integrierten Endpunkt.

Verwenden Sie den Befehl az iot hub message-route fallback show zum Anzeigen des Status der Fallbackroute in Ihrem IoT-Hub.

az iot hub message-route fallback show --hub-name {iothub_name}

Verwenden Sie den Befehl az iot hub message-route fallback set zum Aktivieren oder Deaktivieren der Fallbackroute in Ihrem IoT-Hub.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

Nächste Schritte

In diesem Artikel mit Anleitungen haben Sie erfahren, wie Sie eine Route und einen Endpunkt für Event Hubs, Service Bus-Warteschlangen und -Themen sowie für Azure Storage erstellen.

Weitere Informationen zum Nachrichtenrouting finden Sie im Tutorial: Senden von Gerätedaten an Azure Storage über IoT Hub-Nachrichtenrouting. In diesem Tutorial erstellen Sie eine Speicherroute und testen sie mit einem Gerät in Ihrem IoT-Hub.