Erstellen und Löschen von Routen und Endpunkten mithilfe von Azure Resource Manager

Artikel
04/13/2023

In diesem Artikel wird gezeigt, wie Sie Ihre Azure IoT Hub-Vorlage exportieren, Ihrem IoT-Hub eine Route hinzufügen und dann die Vorlage mithilfe der Azure-Befehlszeilenschnittstelle (Azure CLI) oder von Azure PowerShell auf Ihrem IoT-Hub erneut bereitstellen. Verwenden Sie eine Azure Resource Manager-Vorlage zum Erstellen von Routen und Endpunkten für Azure Event Hubs, Azure Service Bus-Warteschlangen und -Themen sowie für Azure Storage.

Azure Resource Manager-Vorlagen sind nützlich, wenn Sie Ressourcen mithilfe einer JSON-Datei definieren möchten. Jede Azure-Ressource enthält eine Vorlage zum Definieren der Komponenten definiert, die in dieser Ressource verwendet werden. Sie können alle Azure-Ressourcenvorlagen exportieren.

Wichtig

Wenn Sie eine Resource Manager-Vorlage zum Bereitstellen einer Ressource verwenden, ersetzt die Vorlage jede vorhandene Ressource des gerade bereitgestellten Typs.

Wenn Sie einen neuen IoT-Hub erstellen, ist das Überschreiben einer vorhandenen bereitgestellten Ressource kein Problem. Zum Erstellen eines neuen IoT-Hubs können Sie eine Basisvorlage mit den erforderlichen Eigenschaften verwenden, statt eine vorhandene Vorlage aus einem schon bereitgestellten IoT-Hub zu exportieren.

Wenn Sie jedoch einer vorhandenen IoT-Hub-Resource Manager-Vorlage eine Route hinzufügen, verwenden Sie eine Vorlage, die Sie aus Ihrem IoT-Hub exportieren. Auf diese Weise können Sie sicherstellen, dass alle vorhandenen Ressourcen und Eigenschaften verbunden bleiben, nachdem Sie die aktualisierte Vorlage bereitgestellt haben. Ressourcen, die schon bereitgestellt wurden, werden nicht ersetzt. So könnte beispielsweise eine exportierte Resource Manager-Vorlage, die Sie zuvor bereitgestellt haben, Speicherinformationen für Ihren IoT-Hub enthalten, wenn Sie ihn mit dem Speicher verbunden haben.

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 zu den Schritten 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 im Artikel beschriebenen Verfahren werden die folgenden Ressourcen verwendet:

über eine Azure Resource Manager-Vorlage
Ein IoT Hub
Ein Endpunktdienst in Azure

Azure Resource Manager-Vorlage

In diesem Artikel wird eine Azure Resource Manager-Vorlage im Azure-Portal zum Arbeiten mit IoT Hub und anderen Azure-Diensten verwendet. Weitere Informationen zur Verwendung von Resource Manager-Vorlagen finden Sie unter Was sind Azure Resource Manager-Vorlagen?

IoT Hub

Zum Erstellen einer IoT-Hub-Route benötigen Sie einen IoT-Hub, den Sie mithilfe von Azure IoT Hub erstellt haben. Gerätemeldungen und Ereignisprotokolle stammen aus Ihrem IoT-Hub.

Beim Erstellen Ihrer IoT-Hub-Route müssen Sie die folgende Hubressource verwenden:

Ein IoT-Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte zum Erstellen eines IoT-Hubs mithilfe einer Azure Resource Manager-Vorlage (PowerShell) ausführen.

Endpunktdienst

Zum Erstellen einer IoT-Hub-Route benötigen Sie mindestens einen anderen Azure-Dienst, der als Endpunkt für die Route verwendet werden soll. Der Endpunkt empfängt Gerätenachrichten und Ereignisprotokolle. Sie können wählen, welchen Azure-Dienst Sie für einen Endpunkt verwenden möchten, der eine Verbindung mit Ihrer IoT-Hub-Route herstellen soll: Event Hubs, Service Bus-Warteschlangen oder -Themen oder aber Azure Storage.

Sie müssen eine der folgenden Ressourcen verwenden, wenn Sie einen Endpunkt für Ihre IoT-Hub-Route erstellen:

Eine Event Hubs-Ressource (mit Container). Wenn Sie eine neue Event Hubs-Ressource erstellen müssen, lesen Sie den Schnellstart: Erstellen eines Event Hubs mithilfe einer Resource Manager-Vorlage.
Eine Service Bus-Warteschlangenressource. Wenn Sie eine neue Service Bus-Warteschlange erstellen müssen, lesen Sie den Schnellstart: Erstellen eines Service Bus-Namespace und einer Warteschlange mithilfe einer Resource Manager-Vorlage.
Eine Service Bus-Themenressource. Wenn Sie ein neues Service Bus-Thema erstellen müssen, lesen Sie den Schnellstart: Erstellen eines Service Bus-Namespace mit einem Thema und einem Abonnement mithilfe einer Resource Manager-Vorlage.
Eine Azure Storage-Ressource. Informationen zum Erstellen einer neuen Azure Storage-Instanz finden Sie unter Erstellen eines Speicherkontos.

Erstellen einer 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. Anschließend verwenden Sie Routingabfragen zum Filtern von Nachrichten oder Ereignissen, bevor sie zum Endpunkt gelangen.

Sie können einen Event Hub, eine Service Bus-Warteschlange oder ein Service Bus-Thema oder aber ein Azure-Speicherkonto als Endpunkt für Ihre IoT-Hub-Route verwenden. Der Dienst, den Sie zum Erstellen Ihres Endpunkts verwenden, muss in Ihrem Azure-Konto zuerst vorhanden sein.

Exportieren der Resource Manager-Vorlage aus Ihrem IoT-Hub

Exportieren Sie zunächst eine Resource Manager-Vorlage aus Ihrem IoT-Hub, und fügen Sie ihr dann eine Route hinzu.

Navigieren Sie im Azure-Portal zu Ihrem IoT Hub. Wählen Sie im Ressourcenmenü unter Automatisierung die Option Vorlage exportieren aus.
Führen Sie unter Vorlage exportieren auf der Registerkarte Vorlage die folgenden Schritte aus:
1. Zeigen Sie die JSON-Datei an, die für Ihren IoT-Hub generiert wird.
2. Deaktivieren Sie das Kontrollkästchen Parameter einschließen.
3. Wählen Sie Herunterladen aus, um eine lokale Kopie der JSON-Datei herunterzuladen.
Die Vorlage enthält mehrere Platzhalter, über die Sie Ihrem IoT-Hub Features oder Dienste hinzufügen können. Fügen Sie bei diesem Artikel Werte nur den Eigenschaften hinzu, die in routing enthalten oder darunter geschachtelt sind.

Hinzufügen eines neuen Endpunkts zu Ihrer Resource Manager-Vorlage

Suchen Sie in der JSON-Datei nach der Eigenschaft "endpoints": [], die unter "routing" geschachtelt ist. Führen Sie die Schritte zum Hinzufügen eines neuen Endpunkts aus, der auf dem von Ihnen dafür gewählten Azure-Dienst basiert: Event Hubs, Service Bus-Warteschlangen oder -Themen oder aber Azure Storage.

Wenn Sie erfahren möchten, wie eine Event Hubs-Ressource (mit Container) erstellt wird, lesen Sie den Schnellstart: Erstellen eines Event Hubs mithilfe einer Resource Manager-Vorlage.

Rufen Sie im Azure-Portal Ihre primäre Verbindungszeichenfolge aus Ihrer Event Hubs-Ressource ab. Wählen Sie im Bereich Freigegebene Zugriffsrichtlinien der Ressource eine Ihrer Richtlinien aus, um die Informationen zum Schlüssel und zur Verbindungszeichenfolge anzuzeigen. Fügen Sie dem Entitätspfad am Ende der Verbindungszeichenfolge Ihren Event Hub-Namen hinzu. Verwenden Sie z. B. ;EntityPath=my-event-hubs. Dies ist der Name Ihrer Event Hub-Instanz, nicht der Ihres Namespaces.

Verwenden Sie bei name einen eindeutigen Wert für Ihren Event Hubs-Endpunkt. Belassen Sie den Parameter id als leere Zeichenfolge. Der Azure-Dienst stellt einen id-Wert bereit, wenn Sie den Endpunkt bereitstellen.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [],
      "eventHubs": [
            {
               "connectionString": "my Event Hubs connection string + entity path",
               "authenticationType": "keyBased",
               "name": "my-event-hubs-endpoint",
               "id": "",
               "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
               "resourceGroup": "my-resource-group"
            }
      ],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Wenn Sie erfahren möchten, wie eine Service Bus-Warteschlangenressource (ein Namespace und eine Warteschlange) erstellt wird, lesen Sie den Schnellstart: Erstellen eines Service Bus-Namespace und einer Warteschlange mithilfe einer Resource Manager-Vorlage.

Rufen Sie im Azure-Portal Ihre primäre Verbindungszeichenfolge aus Ihrer Service Bus-Ressource ab. Wählen Sie im Bereich Freigegebene Zugriffsrichtlinien der Ressource eine Ihrer Richtlinien aus, um die Informationen zum Schlüssel und zur Verbindungszeichenfolge anzuzeigen. Fügen Sie dem Entitätspfad am Ende der Verbindungszeichenfolge Ihren Event Hub-Namen hinzu. Verwenden Sie z. B. ;EntityPath=my-service-bus-queue. Dies ist der Name Ihrer Warteschlange, nicht der Ihres Namespaces.

Verwenden Sie bei name einen eindeutigen Wert für den Endpunkt Ihrer Service Bus-Warteschlange. Belassen Sie den Parameter id als leere Zeichenfolge. Der Azure-Dienst stellt einen id-Wert bereit, wenn Sie den Endpunkt bereitstellen.

"routing": {
   "endpoints": {
      "serviceBusQueues": [
            {
               "connectionString": "my Service Bus connection string + entity path",
               "authenticationType": "keyBased",
               "name": "my-service-bus-queue-endpoint",
               "id": "",
               "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
               "resourceGroup": "my-resource-group"
            }
      ],
      "serviceBusTopics": [],
      "eventHubs": [],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Wenn Sie eine Service Bus-Themenressource (einen Namespace, ein Thema und ein Abonnement) erstellen müssen, lesen Sie den Schnellstart: Erstellen eines Service Bus-Namespace und eines Thema mithilfe einer Resource Manager-Vorlage.

Rufen Sie im Azure-Portal Ihre primäre Verbindungszeichenfolge aus Ihrer Service Bus-Ressource ab. Wählen Sie im Bereich Freigegebene Zugriffsrichtlinien der Ressource eine Ihrer Richtlinien aus, um die Informationen zum Schlüssel und zur Verbindungszeichenfolge anzuzeigen. Fügen Sie dem Entitätspfad am Ende der Verbindungszeichenfolge Ihren Event Hub-Namen hinzu. Verwenden Sie z. B. ;EntityPath=my-service-bus-topic. Dies ist der Name Ihres Themas, nicht der Ihres Namespaces.

Geben Sie bei name einen eindeutigen Namen für Ihren Endpunkt ein. Belassen Sie den Parameter id als leere Zeichenfolge. Der Azure-Dienst stellt einen id-Wert bereit, wenn Sie den Endpunkt bereitstellen.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [
         {
            "connectionString": "my Service Bus connection string + entity path",
            "authenticationType": "keyBased",
            "name": "my-service-bus-topic-endpoint",
            "id": "",
            "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "resourceGroup": "my-resource-group"
         }
      ],
      "eventHubs": [],
      "storageContainers": [],
      "cosmosDBSqlCollections": []
   },
},

Wenn Sie erfahren möchten, wie eine Azure Storage-Ressource (ein Namespace, ein Thema und ein Abonnement) erstellt werden, lesen Sie Erstellen eines Speicherkontos.

Rufen Sie im Azure-Portal im Bereich Zugriffsschlüssel Ihrer Azure Storage-Ressource Ihre primäre Verbindungszeichenfolge für diese Ressource ab.

"routing": {
   "endpoints": {
      "serviceBusQueues": [],
      "serviceBusTopics": [],
      "eventHubs": [],
      "storageContainers": [
         {
            "connectionString": "my Azure storage connection string",
            "containerName": "my-container",
            "fileNameFormat": "{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.avro",
            "batchFrequencyInSeconds": 100,
            "maxChunkSizeInBytes": 104857600,
            "encoding": "avro",
            "authenticationType": "keyBased",
            "name": "my-storage-endpoint",
            "id": "",
            "subscriptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "resourceGroup": "my-resource-group"
         }
      ],
      "cosmosDBSqlCollections": []
   },
},

Hinzufügen einer neuen Route zu Ihrer Resource Manager-Vorlage

Wechseln Sie in der JSON-Datei zu der unter "routing" geschachtelten Eigenschaft "routes": [], und fügen Sie die folgende neue Route hinzu – je nach dem von Ihnen gewählten Endpunktdienst: Event Hubs, Service Bus-Warteschlangen oder -Themen oder aber Azure Storage.

Die Standard-Fallbackroute sammelt Nachrichten aus DeviceMessages. Wählen Sie eine andere Option, z. B. DeviceConnectionStateEvents. Weitere Informationen zu Quelloptionen finden Sie unter az iot hub route.

Achtung

Wenn Sie vorhandene Werte für "routes" durch die in den folgenden Codebeispielen verwendeten Routenwerte ersetzen, werden die vorhandenen Routen bei Ihrer Bereitstellung entfernt. Wenn Sie vorhandene Routen beibehalten möchten, fügen Sie das neue Routenobjekt der Liste "routes" hinzu.

Weitere Informationen zur Vorlage finden Sie unter Azure Resource Manager template resource definition (Ressourcendefinition für die Azure Resource Manager-Vorlage).

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-event-hubs-endpoint"
        ],
        "isEnabled": true
    }
],

Speichern Sie Ihre JSON-Datei.

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-service-bus-queue-endpoint"
        ],
        "isEnabled": true
    }
],

Speichern Sie Ihre JSON-Datei.

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-service-bus-topic-endpoint"
        ],
        "isEnabled": true
    }
],

Speichern Sie Ihre JSON-Datei.

"routes": [
    {
        "name": "MyIotHubRoute",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
        "my-storage-endpoint"
        ],
        "isEnabled": true
    }
],

Speichern Sie Ihre JSON-Datei.

Bereitstellen der Resource Manager-Vorlage

Nachdem Sie Ihren neuen Endpunkt und die Route zur Resource Manager-Vorlage hinzugefügt haben, können Sie nun die JSON-Datei wieder für Ihren IoT-Hub bereitstellen.

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

New-AzResourceGroupDeployment `
  -Name MyTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "my\path\to\template.json"

Bereitstellung mit Azure Cloud Shell

Weil Azure Cloud Shell in einem Webbrowser ausgeführt wird, können Sie die Vorlagendatei hochladen, bevor Sie den Bereitstellungsbefehl ausführen. Nach dem Hochladen der Datei benötigen Sie nur den Dateinamen der Vorlage (statt des gesamten Dateipfads) zur Verwendung im Parameter template-file.

Screenshot der Schaltfläche in Azure Cloud Shell zum Hochladen einer Datei

Azure-Befehlszeilenschnittstelle
PowerShell

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

New-AzResourceGroupDeployment `
  -Name MyIoTHubTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "template.json"

Hinweis

Wenn bei der Bereitstellung ein Fehler auftritt, verwenden Sie den Schalter -verbose, um Informationen zu den erstellten Ressourcen abzurufen. Verwenden Sie den Schalter -debug, um weitere Informationen zum Debuggen zu erhalten.

Überprüfen der Bereitstellung

Zur Bestätigung, dass Ihre Vorlage in Azure erfolgreich bereitgestellt wurde, wechseln Sie im Azure-Portal zu Ihrer Ressourcengruppenressource. Wählen Sie im Ressourcenmenü unter Einstellungen die Option Bereitstellungen aus, um die Vorlage in einer Liste Ihrer Bereitstellungen anzuzeigen.

Screenshot einer Liste der Bereitstellungen für eine Ressource im Azure-Portal, mit einer hervorgehobenen Testvorlage

Wenn Sie Ihre neue Route im Azure-Portal anzeigen möchten, wechseln Sie zu Ihrer IoT Hub-Ressource. Vergewissern Sie sich im Bereich Nachrichtenrouting auf der Registerkarte Routen, dass Ihre Route dort aufgeführt ist.

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.

Erstellen und Löschen von Routen und Endpunkten mithilfe von Azure Resource Manager

Voraussetzungen

Azure Resource Manager-Vorlage

IoT Hub

Endpunktdienst

Erstellen einer Route

Exportieren der Resource Manager-Vorlage aus Ihrem IoT-Hub

Hinzufügen eines neuen Endpunkts zu Ihrer Resource Manager-Vorlage

Hinzufügen einer neuen Route zu Ihrer Resource Manager-Vorlage

Bereitstellen der Resource Manager-Vorlage

Lokale Bereitstellung

Bereitstellung mit Azure Cloud Shell

Überprüfen der Bereitstellung

Nächste Schritte

Zusätzliche Ressourcen