Zelfstudie: Azure CLI gebruiken om IoT Hub-berichtroutering te configureren

Met berichtroutering kunt u telemetriegegevens verzenden van uw IoT-apparaten naar ingebouwde, met Event Hub compatibele eindpunten of aangepaste eindpunten zoals blobopslag, Service Bus-wachtrijen, Service Bus-onderwerpen en Event Hubs. Als u een aangepaste berichtroutering wilt configureren, maakt u routeringsquery’s om een route aan te passen die overeenkomt met een bepaalde regel. Zodra u deze hebt ingesteld, worden de inkomende gegevens automatisch door de IoT Hub doorgestuurd naar de eindpunten. Als een bericht niet overeen komt met een van de gedefinieerde routeringsquery's, wordt het doorgeleid naar het standaard eindpunt.

In deze tweedelige zelfstudie leert u hoe u deze aangepaste routeringsquery’s kunt instellen en gebruiken met IoT Hub. U stuurt berichten door van een IoT-apparaat naar een of meerdere eindpunten, met inbegrip van blobopslag en een Service Bus-wachtrij. Berichten in de Service Bus-wachtrij worden opgehaald door een logische app en via e-mail verzonden. Berichten waarvoor geen aangepaste berichtroutering is gedefinieerd, worden naar het standaardeindpunt gestuurd, vervolgens opgehaald door Azure Stream Analytics en weergegeven in een Power BI-visualisatie.

Als u deel 1 en 2 van deze zelfstudie wilt afronden, voert u de volgende taken uit:

Deel I: Resources maken, berichtroutering instellen

Deel II: Berichten verzenden naar de hub, gerouteerde resultaten weergeven

Vereisten

• Voor Deel 1 van deze zelfstudie:

  • U hebt een abonnement op Azure nodig. Als u nog geen abonnement op Azure hebt, maak dan een gratis account aan voordat u begint.

• Voor Deel 2 van deze zelfstudie:

  • U moet Deel 1 van deze zelfstudie hebben afgerond en de resources nog tot uw beschikking hebben.
  • Installeer Visual Studio.
  • Toegang tot een Power BI-account voor het analyseren van de Stream Analytics van het standaardeindpunt. (Probeer Power BI gratis uit.)
  • Een werk- of schoolaccount voor het verzenden van e-mailberichten.
  • Zorg ervoor dat de poort 8883 is geopend in de firewall. In het voorbeeld in deze zelfstudie wordt het MQTT-protocol gebruikt, dat communiceert via poort 8883. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

Azure Cloud Shell gebruiken

Azure host Azure Cloud Shell, een interactieve shell-omgeving die u via uw browser kunt gebruiken. U kunt Bash of PowerShell gebruiken met Cloud Shell om met Azure-services te werken. U kunt de vooraf geïnstalleerde opdrachten van Cloud Shell gebruiken om de code in dit artikel uit te voeren zonder dat u iets hoeft te installeren in uw lokale omgeving.

Om Azure Cloud Shell op te starten:

Optie	Voorbeeld/koppeling
Selecteer Nu proberen in de rechterbovenhoek van een codeblok. Als u Uitproberen selecteert, wordt de code niet automatisch gekopieerd naar Cloud Shell.
Ga naar https://shell.azure.com, of selecteer de knop Cloud Shell starten om Cloud Shell in uw browser te openen.
Klik op de knop Cloud Shell in het menu in de balk rechtsboven in de Azure-portal.

Om de code in dit artikel in Azure Cloud Shell uit te voeren:

1. Start Cloud Shell.

2. Selecteer de knop Kopiëren op een codeblok om de code te kopiëren.

3. Plak de code in de Cloud Shell-sessie door CTRL+Shift+V te selecteren in Windows en Linux of door Cmd+Shift+V op macOS te selecteren.

4. Selecteer Invoeren om de code uit te voeren.

Basisresources maken

Voordat u de berichtroutering kunt configureren, moet u een IoT-hub, een opslagaccount en een Service Bus-wachtrij maken. Deze resources kunnen worden gemaakt met behulp van een van de vier artikelen die beschikbaar zijn voor deel 1 van deze zelfstudie: Azure Portal, een Azure Resource Manager-sjabloon, de Azure CLI of Azure PowerShell.

Gebruik dezelfde resourcegroep en -locatie voor alle resources. Vervolgens kunt u alle resources aan het einde in één stap verwijderen door de resourcegroep te verwijderen.

Hieronder vindt u een overzicht van de stappen die in de volgende secties moeten worden uitgevoerd:

1. Maak een resourcegroep.

2. Maak een IoT Hub in de S1-laag. Voeg een consumentengroep toe aan uw IoT Hub. De consumentengroep wordt gebruikt door de Azure Stream Analytics bij het ophalen van gegevens.

   Notitie

   U moet een IoT Hub in een betaalde laag gebruiken om deze zelfstudie te voltooien. Met de gratis laag kunt u slechts één eindpunt instellen, terwijl voor deze zelfstudie meerdere eindpunten zijn vereist.

3. Maak een standaard V1-opslagaccount met Standard_LRS replicatie.

4. Maak een Service Bus-naamruimte en -wachtrij.

5. Maak een apparaat-id voor het gesimuleerde apparaat dat berichten naar uw hub verzendt. Sla de sleutel op voor de testfase. (Als u een Resource Manager-sjabloon maakt, doet u dit na het implementeren van de sjabloon.)

Het script downloaden (optioneel)

Voor het tweede deel van deze zelfstudie downloadt u een Visual Studio-toepassing en voert u deze uit om berichten naar de IoT Hub te verzenden. Een map in de download bevat de Azure Resource Manager-sjabloon en het parameterbestand, evenals de Azure CLI- en PowerShell-scripts.

Als u het voltooide script wilt weergeven, downloadt u de C#-voorbeelden voor Azure IoT. Het main.zip uit. U vindt het Azure CLI-script in de map /iot-hub/Tutorials/Routing/SimulatedDevice/resources/ onder de naam iothub_routing_cli.azcli.

De ADe Azure-CLI gebruiken om uw resources te maken

Kopieer en plak het onderstaande script in Cloud Shell en druk op Enter. Het script wordt met één regel tegelijk uitgevoerd. Met de eerste sectie van het script worden de basisresources voor deze zelfstudie gemaakt, waaronder het opslagaccount, de IoT Hub, de Service Bus-naamruimte en de Service Bus-wachtrij. Bij het doorlopen van de rest van de zelfstudie kopieert u elk scriptblok en plakt u het in Cloud Shell om het uit te voeren.

Er zijn een aantal resourcenamen die wereldwijd uniek moeten zijn, zoals de naam van de IoT Hub en van het opslagaccount. Om dit gemakkelijker te maken, wordt aan die resourcenamen een willekeurige alfanumerieke waarde genaamd randomValue toegevoegd. De randomValue wordt bovenaan het script eenmaal gegenereerd en waar nodig aan de resourcenamen in het hele script toegevoegd. Als u niet wilt dat de waarde willekeurig is, kunt u deze instellen op een lege tekenreeks of op een specifieke waarde.

# This command retrieves the subscription id of the current Azure account. 
# This field is used when setting up the routing queries.
subscriptionID=$(az account show --query id -o tsv)

# Concatenate this number onto the resources that have to be globally unique.
# You can set this to "" or to a specific value if you don't want it to be random.
# This retrieves a random value.
randomValue=$RANDOM

# This command installs the IOT Extension for Azure CLI.
# You only need to install this the first time.
# You need it to create the device identity. 
az extension add --name azure-iot

# Set the values for the resource names that 
#   don't have to be globally unique.
location=westus
resourceGroup=ContosoResources
iotHubConsumerGroup=ContosoConsumers
containerName=contosoresults
iotDeviceName=Contoso-Test-Device

# Create the resource group to be used
#   for all the resources for this tutorial.
az group create --name $resourceGroup \
    --location $location

# The IoT hub name must be globally unique, 
#   so add a random value to the end.
iotHubName=ContosoTestHub$randomValue 
echo "IoT hub name = " $iotHubName

# Create the IoT hub.
az iot hub create --name $iotHubName \
    --resource-group $resourceGroup \
    --sku S1 --location $location

# Add a consumer group to the IoT hub for the 'events' endpoint.
az iot hub consumer-group create --hub-name $iotHubName \
    --name $iotHubConsumerGroup

# The storage account name must be globally unique, 
#   so add a random value to the end.
storageAccountName=contosostorage$randomValue
echo "Storage account name = " $storageAccountName

# Create the storage account to be used as a routing destination.
az storage account create --name $storageAccountName \
    --resource-group $resourceGroup \
    --location $location \
    --sku Standard_LRS

# Get the primary storage account key. 
#    You need this to create the container.
storageAccountKey=$(az storage account keys list \
    --resource-group $resourceGroup \
    --account-name $storageAccountName \
    --query "[0].value" | tr -d '"') 

# See the value of the storage account key.
echo "storage account key = " $storageAccountKey

# Create the container in the storage account. 
az storage container create --name $containerName \
    --account-name $storageAccountName \
    --account-key $storageAccountKey \
    --public-access off

# The Service Bus namespace must be globally unique, 
#   so add a random value to the end.
sbNamespace=ContosoSBNamespace$randomValue
echo "Service Bus namespace = " $sbNamespace

# Create the Service Bus namespace.
az servicebus namespace create --resource-group $resourceGroup \
    --name $sbNamespace \
    --location $location

# The Service Bus queue name must be globally unique, 
#   so add a random value to the end.
sbQueueName=ContosoSBQueue$randomValue
echo "Service Bus queue name = " $sbQueueName

# Create the Service Bus queue to be used as a routing destination.
az servicebus queue create --name $sbQueueName \
    --namespace-name $sbNamespace \
    --resource-group $resourceGroup

# Create the IoT device identity to be used for testing.
az iot hub device-identity create --device-id $iotDeviceName \
    --hub-name $iotHubName

# Retrieve the information about the device identity, then copy the primary key to
#   Notepad. You need this to run the device simulation during the testing phase.
az iot hub device-identity show --device-id $iotDeviceName \
    --hub-name $iotHubName

Nu de basisresources zijn ingesteld, kunt u de berichtroutering configureren.

Berichtroutering instellen

U gaat berichten naar andere resources doorsturen op basis van eigenschappen die door het gesimuleerde apparaat aan het bericht zijn gekoppeld. Berichten die niet aangepast zijn doorgestuurd, worden verzonden naar het standaardeindpunt (berichten/gebeurtenissen). In de volgende zelfstudie stuurt u berichten naar IoT Hub en ziet u dat ze naar de verschillende bestemmingen worden gerouteerd.

In de eerste stap bestaat uit het instellen van het eindpunt waarnaar de gegevens worden gerouteerd. In de tweede stap wordt de berichtroute ingesteld die van dat eindpunt gebruikmaakt. Nadat u de routering hebt ingesteld, kunt u de eindpunten en berichtroutes weergeven in de portal.

Als u een routeringseindpunt wilt maken, gebruikt u az iot hub routing-endpoint create. Als u de berichtroute voor het eindpunt wilt maken, gebruikt u az iot hub route create.

Routeren naar een opslagaccount

Stel eerst het eindpunt voor het opslagaccount in, en stel vervolgens de route in.

Dit zijn de variabelen die worden gebruikt door het script dat moet worden ingesteld in uw Cloud Shell-sessie:

storageConnectionString: Deze waarde wordt opgehaald uit het opslagaccount dat in het vorige script is ingesteld. Het wordt gebruikt door de berichtroutering om toegang te krijgen tot het opslagaccount.

resourceGroup: Deze variabele komt twee keer voor: stel beide in op uw resourcegroep.

endpoint subscriptionID: Dit veld wordt ingesteld op de Azure-abonnements-id voor het eindpunt.

endpointType: Dit veld is het type eindpunt. Deze waarde moet worden ingesteld op azurestoragecontainer, eventhub, servicebusqueue of servicebustopic. Stel deze hier in op azurestoragecontainer.

iotHubName: Dit veld is de naam van de hub waarop de routering wordt uitgevoerd.

containerName: Dit veld is de naam van de container in het opslagaccount waarnaar gegevens worden geschreven.

encoding: Dit veld moet worden ingesteld op avro of json. Dit is de indeling waarin de gegevens worden opgeslagen.

routeName: Dit veld is de naam van de route die u instelt.

endpointName: Dit veld geeft de naam van het eindpunt aan.

enabled: Dit veld wordt standaard ingesteld op true, wat aangeeft dat de berichtroute moet worden ingeschakeld nadat deze is gemaakt.

condition: Dit veld is de query die wordt gebruikt als filter voor berichten die naar dit eindpunt worden verzonden. De queryvoorwaarde voor de berichten die naar de opslag worden doorgestuurd, is level="storage".

Kopieer dit script, plak het in uw Cloud Shell-venster en voer het uit.

##### ROUTING FOR STORAGE ##### 

endpointName="ContosoStorageEndpoint"
endpointType="azurestoragecontainer"
routeName="ContosoStorageRoute"
condition='level="storage"'

# Get the connection string for the storage account.
# Adding the "-o tsv" makes it be returned without the default double quotes around it.
storageConnectionString=$(az storage account show-connection-string \
  --name $storageAccountName --query connectionString -o tsv)

De volgende stap is het maken van het eindpunt van de routering voor het opslagaccount. U geeft ook de container op waarin de resultaten worden opgeslagen. De container is eerder gemaakt toen u het opslagaccount maakte.

# Create the routing endpoint for storage.
az iot hub routing-endpoint create \
  --connection-string $storageConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --container $containerName \
  --resource-group $resourceGroup \
  --encoding avro

Maak vervolgens de route voor het eindpunt van de opslag. De berichtroute geeft aan waarnaartoe de berichten moeten worden verzonden die voldoen aan de query.

# Create the route for the storage endpoint.
az iot hub route create \
  --name $routeName \
  --hub-name $iotHubName \
  --source devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

Routeren naar een Service Bus-wachtrij

Stel nu de routering in voor de Service Bus-wachtrij. Als u de verbindingsreeks voor de Service Bus-wachtrij wilt ophalen, moet u een autorisatieregel maken waarvoor de juiste rechten zijn gedefinieerd. Met het volgende script maakt u een autorisatieregel voor de Service Bus-wachtrij met de naam sbauthrule, en stelt u de rechten in op Listen Manage Send. Zodra deze autorisatieregel is gedefinieerd, kunt u deze gebruiken om de verbindingsreeks voor de wachtrij op te halen.

# Create the authorization rule for the Service Bus queue.
az servicebus queue authorization-rule create \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --rights Listen Manage Send \
  --subscription $subscriptionID

Gebruik nu de autorisatieregel om de verbindingsreeks voor de Service Bus-wachtrij op te halen.

# Get the Service Bus queue connection string.
# The "-o tsv" ensures it is returned without the default double-quotes.
sbqConnectionString=$(az servicebus queue authorization-rule keys list \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --subscription $subscriptionID \
  --query primaryConnectionString -o tsv)

# Show the Service Bus queue connection string.
echo "service bus queue connection string = " $sbqConnectionString

Stel nu het eindpunt van de routering in en de berichtroute voor de Service Bus-wachtrij. Dit zijn de variabelen die worden gebruikt door het script dat moet worden ingesteld in uw Cloud Shell-sessie:

endpointName: Dit veld geeft de naam van het eindpunt aan.

endpointType: Dit veld is het type eindpunt. Deze waarde moet worden ingesteld op azurestoragecontainer, eventhub, servicebusqueue of servicebustopic. Stel deze hier in op servicebusqueue.

routeName: Dit veld is de naam van de route die u instelt.

condition: Dit veld is de query die wordt gebruikt als filter voor berichten die naar dit eindpunt worden verzonden. De queryvoorwaarde voor de berichten die worden gerouteerd naar de Service Bus-wachtrij, is level="critical".

Hier is de Azure CLI voor het eindpunt van de routering en de berichtroute voor de Service Bus-wachtrij.

endpointName="ContosoSBQueueEndpoint"
endpointType="ServiceBusQueue"
routeName="ContosoSBQueueRoute"
condition='level="critical"'

# Set up the routing endpoint for the Service Bus queue.
# This uses the Service Bus queue connection string.
az iot hub routing-endpoint create \
  --connection-string $sbqConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --resource-group $resourceGroup 

# Set up the message route for the Service Bus queue endpoint.
az iot hub route create --name $routeName \
  --hub-name $iotHubName \
  --source-type devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

Berichtroutering weergeven in de portal

Nu uw eindpunten en berichtroutes zijn ingesteld, kunt u de configuratie ervan in de portal bekijken. Meld u aan bij Azure Portal en ga naar Resourcegroepen. Selecteer vervolgens de resourcegroep en vervolgens uw hub (de naam van de hub begint in deze zelfstudie met ContosoTestHub). U ziet het IoT Hub-deelvenster.

Selecteer Berichtroutering in de opties voor IoT Hub. De routes die u hebt ingesteld, worden weergegeven.

Selecteer in het scherm Berichtroutering de optie Aangepaste eindpunten om de eindpunten weer te geven die u voor de routes hebt gedefinieerd.

Volgende stappen

Nu u de resources hebt ingesteld en de berichtroutes hebt geconfigureerd, gaat u door naar de volgende zelfstudie om te leren hoe u berichten naar de IoT Hub verzendt en om te zien hoe ze naar de verschillende bestemmingen worden gerouteerd.