Självstudie: Använda Azure CLI för att konfigurera IoT Hub routning av meddelanden

Med meddelanderoutning kan du skicka telemetridata från dina IoT-enheter till inbyggda Event Hub-kompatibla slutpunkter eller anpassade slutpunkter som bloblagring, Service Bus-köer, Service Bus-ämnen och Event Hubs. Om du vill konfigurera anpassad meddelanderoutning skapar du routningsfrågor för att anpassa vägen som matchar ett visst villkor. Därefter dirigeras inkommande data automatiskt till slutpunkterna av IoT Hub. Om ett meddelande inte matchar någon av de definierade routningsfrågorna dirigeras det till standardslutpunkten.

I den här självstudien i två delar lär du dig att konfigurera och använda dessa anpassade routningsfrågor med IoT Hub. Du dirigerar meddelanden från en IoT-enhet till en av flera slutpunkter, inklusive bloblagring och en Service Bus kö. Meddelanden till Service Bus hämtas av en logikapp och skickas via e-post. Meddelanden som inte har anpassad meddelanderoutning definierad skickas till standardslutpunkten och hämtas sedan av Azure Stream Analytics och visas i en Power BI visualisering.

Utför följande uppgifter för att slutföra del 1 och 2 av den här självstudien:

Del I: Skapa resurser, konfigurera meddelandedirigering

Del II: Skicka meddelanden till hubben, visa dirigerade resultat

Förutsättningar

• För del 1 av den här självstudien:

  • Du måste ha en Azure-prenumeration. Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar.

• För del 2 av den här självstudien:

  • Du måste ha slutfört del 1 av den här självstudien och ha resurserna fortfarande tillgängliga.
  • Installera Visual Studio.
  • Ha åtkomst till ett Power BI för att analysera standardslutpunktens Stream Analytics. (Prova Power BI utan kostnad.)
  • Ha ett arbets- eller skolkonto för att skicka e-postaviseringar.
  • Kontrollera att port 8883 är öppen i brandväggen. Exemplet i den här självstudien använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att komma runt det här problemet finns i Ansluta till IoT Hub (MQTT).

Använda Azure Cloud Shell

Azure är värd för Azure Cloud Shell, en interaktiv gränssnittsmiljö som du kan använda via webbläsaren. Du kan använda antingen Bash eller PowerShell med Cloud Shell för att arbeta med Azure-tjänster. Du kan använda förinstallerade Cloud Shell-kommandon för att köra koden i den här artikeln utan att behöva installera något i din lokala miljö.

Så här startar du Azure Cloud Shell:

Alternativ	Exempel/länk
Välj Prova i det övre högra hörnet av ett kodblock. Om du väljer Prova kopieras koden inte automatiskt till Cloud Shell.
Gå till https://shell.azure.com eller Välj knappen Starta Cloud Shell för att öppna Cloud Shell i webbläsaren.
Välj knappen Cloud Shell på menyn längst upp till höger i Azure-portalen.

Så här kör du koden i den här artikeln i Azure Cloud Shell:

1. Starta Cloud Shell.

2. Kopiera koden genom att klicka på knappen Kopiera på ett kodblock.

3. Klistra in koden i Cloud Shell-sessionen genom att välja Ctrl+Skift+V på Windows och Linux eller genom att välja Cmd+Skift+V på macOS.

4. Välj Retur för att köra koden.

Skapa bas resurser

Innan du kan konfigurera meddelanderoutning måste du skapa en IoT-hubb, ett lagrings konto och en Service Bus kö. Dessa resurser kan skapas med hjälp av någon av de fyra artiklarna som är tillgängliga i del 1 av den här självstudien: Azure Portal, en Azure Resource Manager mall, Azure CLI eller Azure PowerShell.

Använd samma resursgrupp och plats för alla resurser. När du är klar kan du ta bort alla resurser i ett steg genom att ta bort resurs gruppen.

Nedan visas en sammanfattning av de steg som ska utföras i följande avsnitt:

1. Skapa en resurs grupp.

2. Skapa en IoT-hubb på S1-nivån. Lägg till en konsumentgrupp till din IoT-hubb. Konsumentgruppen används av Azure Stream Analytics när data hämtas.

   Anteckning

   Du måste använda en Iot-hubb på en betalnivå för att slutföra den här självstudien. På den kostnadsfria nivån kan bara ställa in en slutpunkt, och den här självstudien kräver flera slutpunkter.

3. Skapa ett V1-standardlagringskonto med Standard_LRS-replikering.

4. Skapa ett namnområde och en kö för Service Bus.

5. Skapa en enhetsidentitet för den simulerade enheten som skickar meddelanden till din hubb. Spara nyckeln för testfasen. (Om du skapar en Resource Manager-mall görs detta när du har distribuerat mallen.)

Ladda ned skriptet (valfritt)

I den andra delen av den här självstudien laddar du ned och kör Visual Studio program för att skicka meddelanden till IoT Hub. Det finns en mapp i nedladdningen som innehåller Azure Resource Manager-mall och parameterfil, samt Azure CLI- och PowerShell-skript.

Om du vill visa det färdiga skriptet laddar du ned Azure IoT C#-exempel. Packa upp main.zip fil. Azure CLI-skriptet finns i /iot-hub/Tutorials/Routing/SimulatedDevice/resources/ som iothub_routing_cli.azcli.

Använda Azure CLI för att skapa dina resurser

Kopiera och klistra in skriptet nedan i Cloud Shell och tryck på Retur. Skriptet körs en rad i taget. Det här första avsnittet av skriptet skapar basresurserna för den här självstudien, inklusive lagringskontot, IoT Hub, Service Bus namnområdet och Service Bus kön. När du går igenom resten av självstudien kopierar du varje block med skript och klistrar in det i Cloud Shell för att köra det.

Det finns flera resursnamn som måste vara globalt unika, till exempel IoT Hub namn och lagringskontonamn. För att underlätta detta läggs resursnamnen till med ett slumpmässigt alfanumeriskt värde som kallas randomValue. randomValue genereras en gång överst i skriptet och läggs till i resursnamnen efter behov i hela skriptet. Om du inte vill att det ska vara slumpmässigt kan du ange det till en tom sträng eller till ett specifikt värde.

# 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 när basresurserna har konfigurerats kan du konfigurera meddelanderoutning.

Konfigurera meddelandedirigering

Du kommer att dirigera meddelanden till olika resurser baserat på egenskaper som är anslutna till meddelandet av den simulerade enheten. Meddelanden som inte är dirigeringsanpassade skickas till standardslutpunkten (meddelanden/händelser). I nästa självstudie skickar du meddelanden till IoT Hub och kan se att de dirigeras till olika destinationer.

Det första steget är att konfigurera slut punkten som data ska dirigeras till. Det andra steget är att konfigurera den meddelande väg som använder den slut punkten. När du har konfigurerat routningen kan du Visa slut punkterna och meddelande vägarna i portalen.

Om du vill skapa en slutpunkt för routning använder du az iot hub routing-endpoint create. Om du vill skapa meddelandevägen för slutpunkten använder du az iot hub route create.

Dirigera till ett lagringskonto

Konfigurera först slutpunkten för lagringskontot och konfigurera sedan vägen.

Det här är de variabler som används av skriptet som måste anges i din Cloud Shell session:

storageConnectionString: Det här värdet hämtas från lagringskontot som konfigurerades i föregående skript. Den används av meddelanderoutning för att få åtkomst till lagringskontot.

resourceGroup: Det finns två förekomster av resursgruppen – ställ in dem på din resursgrupp.

endpoint subscriptionID: Det här fältet är inställt på Azure subscriptionID för slutpunkten.

endpointType: Det här fältet är typen av slutpunkt. Det här värdet måste anges till azurestoragecontainer , eventhub , eller servicebusqueue servicebustopic . För dina syften här anger du det till azurestoragecontainer .

iotHubName: Det här fältet är namnet på den hubb som ska göra routningen.

containerName: Det här fältet är namnet på containern i lagringskontot som data ska skrivas till.

encoding: Det här fältet blir antingen avro eller json . Detta anger formatet för lagrade data.

routeName: Det här fältet är namnet på den väg som du ställer in.

endpointName: Det här fältet är namnet som identifierar slutpunkten.

aktiverad: Det här fältet är true som standard , vilket anger att meddelandevägen ska aktiveras när den har skapats.

villkor: Det här fältet är den fråga som används för att filtrera efter meddelanden som skickas till den här slutpunkten. Frågevillkoret för meddelanden som dirigeras till lagring är level="storage" .

Kopiera det här skriptet och klistra in det i Cloud Shell och kör det.

##### 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)

Nästa steg är att skapa slutpunkten för routning för lagringskontot. Du kan också ange den container där resultatet ska lagras. Containern skapades tidigare när lagringskontot skapades.

# 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

Skapa sedan vägen för lagringsslutpunkten. Meddelandevägen anger var meddelanden som uppfyller frågespecifikationen ska skickas.

# 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

Dirigera till en Service Bus kö

Konfigurera nu routning för Service Bus-kön. Om du vill hämta anslutningssträngen Service Bus kön måste du skapa en auktoriseringsregel som har rätt definierade rättigheter. Följande skript skapar en auktoriseringsregel för Service Bus med namnet sbauthrule och anger behörigheterna till Listen Manage Send . När den här auktoriseringsregeln har definierats kan du använda den för att hämta anslutningssträngen för kön.

# 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

Använd auktoriseringsregeln för att hämta anslutningssträngen till Service Bus kön.

# 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

Konfigurera nu routningsslutpunkten och meddelandevägen för Service Bus kön. Det här är de variabler som används av skriptet som måste anges i din Cloud Shell session:

endpointName: Det här fältet är namnet som identifierar slutpunkten.

endpointType: Det här fältet är typen av slutpunkt. Det här värdet måste anges till azurestoragecontainer , eventhub , eller servicebusqueue servicebustopic . För dina syften här anger du det till servicebusqueue .

routeName: Det här fältet är namnet på den väg som du ställer in.

villkor: Det här fältet är den fråga som används för att filtrera efter meddelanden som skickas till den här slutpunkten. Frågevillkoret för meddelanden som dirigeras till den Service Bus kön är level="critical" .

Här är Azure CLI för routningsslutpunkten och meddelandevägen för Service Bus kön.

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

Visa meddelanderoutning i portalen

Nu när dina slutpunkter och meddelandevägar har ställts in kan du visa deras konfiguration i portalen. Logga in på Azure Portal och gå till Resursgrupper. Välj sedan din resursgrupp och välj sedan hubben (hubbnamnet börjar med i den här ContosoTestHub självstudien). Du ser IoT Hub fönstret.

I alternativen för IoT Hub väljer du Meddelanderoutning. De vägar som du har ställt in visas.

På skärmen Meddelanderoutning väljer du Anpassade slutpunkter för att se de slutpunkter som du har definierat för vägarna.

Nästa steg

Nu när resurserna har konfigurerats och meddelandevägarna har konfigurerats går du vidare till nästa självstudie för att lära dig hur du skickar meddelanden till IoT-hubben och ser hur de dirigeras till olika mål.