Routes en eindpunten maken en verwijderen met behulp van de Azure CLI

In dit artikel leest u hoe u Azure IoT Hub-routes en -eindpunten beheert met behulp van de Azure CLI. Leer hoe u de Azure CLI gebruikt om routes en eindpunten te maken voor Azure Event Hubs, Azure Service Bus-wachtrijen en onderwerpen, Azure Storage en Cosmos DB.

Zie IoT Hub-berichtroutering gebruiken om apparaat-naar-cloud-berichten naar verschillende eindpunten te verzenden voor meer informatie over hoe routering werkt in IoT Hub. Zie zelfstudie: Apparaatgegevens verzenden naar Azure Storage met behulp van IoT Hub-berichtroutering om stapsgewijs een route in te stellen waarmee berichten naar de opslag worden verzonden en vervolgens op een gesimuleerd apparaat worden getest.

Vereisten

De procedures die in het artikel worden beschreven, gebruiken de volgende bronnen:

• De Azure CLI
• Een IoT-hub
• Een eindpuntservice in Azure

Azure-CLI

In dit artikel wordt de Azure CLI gebruikt om te werken met IoT Hub en andere Azure-services. U kunt kiezen hoe u toegang krijgt tot de Azure CLI:

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

IoT Hub

Een IoT-hub in uw Azure-abonnement hebben. Als u nog geen hub hebt, kunt u de stappen volgen in Een IoT-hub maken.

Eindpuntservice

U hebt ten minste één andere Azure-service nodig om te gebruiken als eindpunt voor de route. Het eindpunt ontvangt apparaatberichten en gebeurtenislogboeken.

Bepaal welke Azure-service u wilt gebruiken als eindpunt voor het ontvangen van gerouteerde apparaat- en gebeurtenisgegevens: een Event Hub, een servicewachtrij of onderwerp, een opslagaccount of een Cosmos DB-container. Voor de service die u wilt gebruiken, voert u de stappen uit om een eindpuntservice te maken.

Event Hubs

1. Een Event Hubs-naamruimte en een Event Hub maken. Zie quickstart: Een Event Hub maken met behulp van de Azure CLI voor meer informatie.

2. Maak een autorisatieregel die wordt gebruikt om IoT Hub toestemming te geven om gegevens naar de Event Hub te verzenden.

   Tip

   De name waarde RootManageSharedAccessKey van de parameter is de standaardnaam waarmee claims beheren, verzenden, luisteren (toegang) zijn toegestaan. Als u de claims wilt beperken, geeft u de name parameter uw eigen unieke naam en neemt u de --rights vlag op gevolgd door een van de claims. Bijvoorbeeld: --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
   

   Zie Toegang tot Azure Event Hubs autoriseren voor meer informatie.

Service Bus-wachtrij

1. Maak een Service Bus-naamruimte en -wachtrij. Zie De Azure CLI gebruiken om een Service Bus-naamruimte en een wachtrij te maken voor meer informatie.

2. Maak een autorisatieregel die IoT Hub toestemming geeft om gegevens naar de wachtrij te verzenden. Gebruik namehiervoor een unieke waarde voor uw autorisatieregel.

   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
   

   Zie az servicebus queue authorization-rule create voor meer opties voor autorisatieregels.

Service Bus-onderwerp

Maak een Service Bus-naamruimte, -onderwerp en -abonnement. Zie Azure CLI gebruiken om een Service Bus-onderwerp en abonnementen voor het onderwerp te maken voor meer informatie.

Azure Storage

1. Een opslagaccount maken. Zie Een opslagaccount maken voor meer informatie.

2. Maak een container in uw opslagaccount. Zie Blob-containers beheren met behulp van Azure CLI voor meer informatie

Cosmos DB

Maak een Cosmos DB-account voor SQL API en een Cosmos DB-container. Zie Een Azure Cosmos DB voor NoSQL maken voor meer informatie.

Een eindpunt maken

Alle IoT Hub-routes verwijzen naar een eindpunt, dat het gerouteerde apparaat en de gebeurtenisgegevens ontvangt. Meer dan één route kan verwijzen naar hetzelfde eindpunt. Momenteel ondersteunt IoT Hub eindpunten voor Event Hubs, Service Bus-wachtrijen of onderwerpen, Opslag en Cosmos DB. Een exemplaar van de service die u voor uw eindpunt gebruikt, moet aanwezig zijn in uw Azure-abonnement voordat u het eindpunt maakt.

Notitie

In dit artikel wordt gebruikgemaakt van de opdrachtgroep az iot hub message-endpoint , die is geïntroduceerd in versie 0.19.0 van de azure-iot-extensie voor de Azure CLI. In eerdere versies van de azure-iot-extensie is gebruikgemaakt van de opdrachtgroep az iot hub routing-endpoint . Deze is vergelijkbaar en wordt nog steeds ondersteund, maar biedt geen ondersteuning voor het maken van Cosmos DB-eindpunten.

Gebruik de volgende opdracht om bij te werken naar de nieuwste versie van de azure-iot-extensie:

az extension update --name azure-iot

Event Hubs

Als u een Event Hubs-eindpunt wilt maken, gebruikt u de autorisatieregel die u hebt gemaakt in de vereisten.

1. Gebruik de opdracht az eventhubs eventhub authorization-rule keys list om uw autorisatieregel weer te geven. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   eventhub_group	Resourcegroep van de Event Hub.
   eventhub_namespace	Naam van de Event Hubs-naamruimte.
   eventhub_name	Naam van de Event Hub.
   rule_name	De naam van de autorisatieregel voor de Event Hub. Als u het voorbeeld in de vereisten hebt gekopieerd, is RootManageSharedAccessKeydeze naam.

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

2. Kopieer uw Event Hub-verbindingsreeks uit de uitvoer.

3. Gebruik de opdracht az iot hub message-endpoint create eventhub om uw aangepaste eindpunt te maken. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar dit eindpunt wordt gemaakt.
   endpoint_name	Een unieke naam voor het nieuwe eindpunt.
   eventhub_subscription	Abonnements-id van de Event Hub. Dit argument kan worden weggelaten als de Event Hub zich in hetzelfde abonnement bevindt als de IoT-hub.
   eventhub_group	Resourcegroep van de Event Hub. Dit argument kan worden weggelaten als de Event Hub zich in dezelfde resourcegroep bevindt als de IoT-hub.
   eventhub_connection_string	De verbindingsreeks die u hebt gekopieerd uit de event hub-autorisatieregel.

   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-wachtrij

Als u een Service Bus-wachtrijeindpunt wilt maken, gebruikt u de autorisatieregel die u hebt gemaakt in de vereisten.

1. Gebruik de opdracht az servicebus queue authorization-rule keys list om uw Service Bus-wachtrij op te halen verbindingsreeks. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   queue_group	Resourcegroep van de Service Bus-wachtrij.
   queue_namespace	Naam van de Service Bus-wachtrijnaamruimte.
   queue_name	De naam van de wachtrij.
   rule_name	De naam van de autorisatieregel voor de wachtrij. Als u het voorbeeld in de vereisten hebt gekopieerd, is my-auth-ruledeze naam.

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

2. Kopieer uw Service Bus-wachtrij verbindingsreeks uit de uitvoer.

3. Gebruik de opdracht az iot hub message-endpoint create servicebus-queue om uw aangepaste eindpunt te maken. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar dit eindpunt wordt gemaakt.
   endpoint_name	Een unieke naam voor het nieuwe eindpunt.
   queue_connection_string	De verbindingsreeks die u hebt gekopieerd uit de autorisatieregel voor de Service Bus-wachtrij.
   queue_subscription	Abonnements-id van de Service Bus-wachtrij. Dit argument kan worden weggelaten als de wachtrij zich in hetzelfde abonnement bevindt als de IoT-hub.
   queue_group	Resourcegroep van de Service Bus-wachtrij. Dit argument kan worden weggelaten als de wachtrij zich in dezelfde resourcegroep bevindt als de IoT-hub.

   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-onderwerp

1. Gebruik de lijst met autorisatieregels voor az servicebus topic om uw Service Bus-onderwerp op te halen verbindingsreeks. De standaardnaam van uw autorisatieregel die wordt geleverd met een nieuwe naamruimte is RootManageSharedAccessKey. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   topic_group	Resourcegroep van het Service Bus-onderwerp.
   topic_namespace	Naam van de Service Bus-onderwerpnaamruimte.
   topic_name	Naam van het onderwerp.

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

2. Kopieer uw Service Bus-onderwerp verbindingsreeks uit de uitvoer.

3. Gebruik de opdracht az iot hub message-endpoint create servicebus-topic om uw aangepaste eindpunt te maken. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar dit eindpunt wordt gemaakt.
   endpoint_name	Een unieke naam voor het nieuwe eindpunt.
   topic_connection_string	De verbindingsreeks die u hebt gekopieerd uit de autorisatieregel voor Service Bus-onderwerpen.
   topic_subscription	Abonnements-id van het Service Bus-onderwerp. Dit argument kan worden weggelaten als het onderwerp zich in hetzelfde abonnement bevindt als de IoT-hub.
   topic_group	Resourcegroep van het Service Bus-onderwerp. Dit argument kan worden weggelaten als het onderwerp zich in dezelfde resourcegroep bevindt als de IoT-hub.

   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

1. Gebruik de opdracht az storage account show-connection-string om de verbindingsreeks op te halen uit uw Azure Storage-resource om een eindpunt te maken. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   storage_group	Resourcegroep van het opslagaccount.
   storage_name	Naam van het opslagaccount.

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

2. Kopieer uw opslagaccount verbindingsreeks uit de uitvoer.

3. Gebruik de opdracht az iot hub message-endpoint create storage-container om een nieuw Azure Storage-eindpunt te maken. Gebruik voor alle andere parameters waarden voor uw scenario. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar dit eindpunt wordt gemaakt.
   endpoint_name	Een unieke naam voor het nieuwe eindpunt.
   storage_connection_string	De verbindingsreeks die u hebt gekopieerd uit de opdracht voor het opslagaccount.
   container_name	De naam van de container in uw opslagaccount waar de gegevens worden verzonden.
   storage_subscription	Abonnements-id van de Service Bus-opslag. Dit argument kan worden weggelaten als de opslag zich in hetzelfde abonnement bevindt als de IoT-hub.
   storage_group	Resourcegroep van de Service Bus-opslag. Dit argument kan worden weggelaten als het onderwerp zich in dezelfde resourcegroep bevindt als de IoT-hub.

   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. Gebruik de opdracht az cosmosdb keys list om de verbindingsreeks op te halen uit uw Cosmos DB-databaseaccount.

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

2. Kopieer uw Cosmos DB-verbindingsreeks uit de uitvoer.

3. Gebruik de opdracht az iot hub message-endpoint create cosmosdb-container om uw aangepaste eindpunt te maken. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar dit eindpunt wordt gemaakt.
   endpoint_name	Een unieke naam voor het nieuwe eindpunt.
   cosmosdb_connection_string	De verbindingsreeks die u hebt gekopieerd uit de cosmos DB-accountopdracht.
   container_name	De naam van de container in uw Cosmos DB-account waar de gegevens worden verzonden.
   database_name	De naam van de database in uw Cosmos DB-account waar de gegevens worden verzonden.
   cosmosdb_subscription	Abonnements-id van het Cosmos DB-databaseaccount. Dit argument kan worden weggelaten als de database zich in hetzelfde abonnement bevindt als de IoT-hub.
   cosmosdb_group	Resourcegroep van het Cosmos DB-databaseaccount. Dit argument kan worden weggelaten als de database zich in dezelfde resourcegroep bevindt als de IoT-hub.

   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
   

   Notitie

   Als u beheerde identiteiten gebruikt in plaats van verbindingsreeks, gebruikt u de opdracht az cosmosdb sql role assignment create om uw identiteit te verifiëren bij het Cosmos DB-account.

   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"
   

Een eindpunt verwijderen

Als u een eindpunt uit uw IoT-hub wilt verwijderen, gebruikt u de opdracht az iot hub message-endpoint delete . Met deze opdracht kunt u één eindpunt verwijderen, alle eindpunten van één type verwijderen of alle eindpunten uit een hub verwijderen.

Met de volgende opdracht worden bijvoorbeeld alle eindpunten in een IoT-hub verwijderd die verwijzen naar opslagbronnen:

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

Een IoT Hub-route maken

In IoT Hub kunt u een route maken om berichten te verzenden of gebeurtenissen vast te leggen. Elke route heeft een gegevensbron en een eindpunt. De gegevensbron is waar berichten of gebeurtenislogboeken vandaan komen. Het eindpunt is waar de berichten of gebeurtenislogboeken terechtkomen. U kiest locaties voor de gegevensbron en het eindpunt wanneer u een nieuwe route in uw IoT-hub maakt. U kunt desgewenst query's toevoegen aan berichtroutes om berichten of gebeurtenissen te filteren voordat ze naar het eindpunt gaan.

Notitie

In dit artikel wordt gebruikgemaakt van de opdrachtgroep az iot hub message-route , die is geïntroduceerd in versie 0.19.0 van de azure-iot-extensie voor de Azure CLI. In eerdere versies van de azure-iot-extensie is gebruikgemaakt van de opdrachtgroep az iot hub route , die vergelijkbaar is en nog steeds wordt ondersteund.

Gebruik de volgende opdracht om bij te werken naar de nieuwste versie van de azure-iot-extensie:

az extension update --name azure-iot

1. Gebruik de opdracht az iot hub message-route create om een nieuwe IoT Hub-route te maken met behulp van dat eindpunt. Geef de volgende waarden op voor de parameters van de tijdelijke aanduiding:

   parameter	waarde
   iothub_name	De naam van de IoT-hub waar deze route wordt gemaakt.
   route_name	Een unieke naam voor de nieuwe route.
   endpoint_name	De naam van het eindpunt waarnaar de route gegevens verzendt.
   data_source	De bron van de route. Geaccepteerde waarden zijn: deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, , , invalidof twinchangeevents.

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

2. Als u wilt controleren of de nieuwe route zich in uw IoT-hub bevindt, gebruikt u de opdracht az iot hub message-route list om alle routes in uw IoT-hub weer te geven:

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

   Als het goed is, ziet u een antwoord in de Azure CLI die vergelijkbaar is met dit voorbeeld:

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

Een IoT Hub-route bijwerken

U kunt enkele eigenschappen van een route bijwerken nadat deze is gemaakt. U kunt de bron-, eindpunt-, voorwaarde- of ingeschakelde status van een bestaande route wijzigen.

Gebruik de opdracht az iot hub message-route show om de details van een route weer te geven.

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

Gebruik de opdracht az iot hub message-route update om de eigenschappen van een route bij te werken. Met de volgende opdracht wordt bijvoorbeeld de bron van de route bijgewerkt.

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

Een IoT Hub-route verwijderen

Gebruik de opdracht az iot hub message-route delete om een route uit uw IoT-hub te verwijderen.

Als u een route verwijdert, wordt het eindpunt niet verwijderd omdat andere routes naar hetzelfde eindpunt kunnen verwijzen. Als u een eindpunt wilt verwijderen, kunt u dit afzonderlijk doen van het verwijderen van een route.

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

De terugvalroute beheren

De terugvalroute verzendt alle berichten van devicemessages de bron die niet voldoen aan queryvoorwaarden op een van de bestaande routes naar het ingebouwde eindpunt.

Gebruik de opdracht az iot hub message-route fallback show om de status van de terugvalroute in uw IoT-hub te bekijken.

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

Gebruik de opdracht az iot hub message-route fallback set om de terugvalroute in of uit te schakelen in uw IoT-hub.

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

Volgende stappen

In dit artikel hebt u geleerd hoe u een route en eindpunt maakt voor Event Hubs, Service Bus-wachtrijen en onderwerpen en Azure Storage.

Zie zelfstudie: Apparaatgegevens verzenden naar Azure Storage met behulp van IoT Hub-berichtroutering voor meer informatie over berichtroutering. In de zelfstudie maakt u een opslagroute en test u deze met een apparaat in uw IoT-hub.