Självstudie: Använda en Azure Resource Manager 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.)

Meddelanderoutning

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.

Ladda ned mallen och parameterfilen

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

Ladda ned Azure IoT C#-exemplen nu. Packa upp main.zip fil. Mallen Resource Manager och parameterfilen finns i /iot-hub/Tutorials/Routing/SimulatedDevice/resources/ som template_iothub.json och template_iothub_parameters.json.

Skapa dina resurser

Du kommer att använda en Azure Resource Manager (RM)-mall för att skapa alla dina resurser. Azure CLI- och PowerShell-skripten kan köras några rader i taget. En RM-mall distribueras i ett enda steg. Den här artikeln visar avsnitten separat för att hjälpa dig att förstå vart och ett. Sedan visas hur du distribuerar mallen och skapar den virtuella enheten för testning. När mallen har distribuerats kan du visa konfigurationen för meddelanderoutning i portalen.

Det finns flera resursnamn som måste vara globalt unika, till exempel IoT Hub namn och lagringskontonamn. För att göra det enklare att namnge resurserna konfigureras dessa resursnamn för att lägga till ett slumpmässigt alfanumeriskt värde som genereras från aktuellt datum/tid.

Om du tittar på mallen ser du var variabler har ställts in för dessa resurser som tar parametern som skickades in och sammanfogar randomValue till parametern.

I följande avsnitt beskrivs de parametrar som används.

Parametrar

De flesta av dessa parametrar har standardvärden. De som slutar med _in sammanfogas med randomValue för att göra dem globalt unika.

randomValue: Det här värdet genereras från det aktuella datumet/tiden när du distribuerar mallen. Det här fältet finns inte i parameterfilen eftersom det genereras i själva mallen.

subscriptionId: Det här fältet är inställt på den prenumeration som du distribuerar mallen till. Det här fältet finns inte i parameterfilen eftersom det har angetts åt dig.

IoTHubName_in: Det här fältet är IoT Hub namn, som sammanfogas med randomValue så att det är globalt unikt.

location: Det här fältet är den Azure-region som du distribuerar till, till exempel "westus".

consumer_group: Det här fältet är konsumentgruppen som angetts för meddelanden som kommer via slutpunkten för routning. Den används för att filtrera resultat i Azure Stream Analytics. Det finns till exempel hela dataströmmen där du får allt, eller om du har data som kommer med consumer_group inställt på Contoso kan du konfigurera en Azure Stream Analytics-dataström (och Power BI-rapport) för att endast visa dessa poster. Det här fältet används i del 2 av den här självstudien.

sku_name: Det här fältet är skalningen för IoT Hub. Det här värdet måste vara S1 eller högre. en kostnadsfri nivå fungerar inte för den här självstudien eftersom den inte tillåter flera slutpunkter.

sku_units: Det här fältet följer med sku_name, och är antalet IoT Hub enheter som kan användas.

d2c_partitions: Det här fältet är antalet partitioner som används för händelseströmmen.

storageAccountName_in: Det här fältet är namnet på det lagringskonto som ska skapas. Meddelanden dirigeras till en container i lagringskontot. Det här fältet sammanfogas med randomValue för att göra det globalt unikt.

storageContainerName: Det här fältet är namnet på containern där meddelandena som dirigeras till lagringskontot lagras.

storage_endpoint: Det här fältet är namnet på lagringskontots slutpunkt som används av meddelanderoutning.

service_bus_namespace_in: Det här fältet är namnet på Service Bus namnområdet som ska skapas. Det här värdet sammanfogas med randomValue för att göra det globalt unikt.

service_bus_queue_in: Det här fältet är namnet på den Service Bus som används för att dirigera meddelanden. Det här värdet sammanfogas med randomValue för att göra det globalt unikt.

AuthRules_sb_queue: Det här fältet är auktoriseringsreglerna för Service Bus-kön som används för att hämta anslutningssträngen för kön.

Variabler

Dessa värden används i mallen och härleds huvudsakligen från parametrar.

queueAuthorizationRuleResourceId: Det här fältet är ResourceId för auktoriseringsregeln för Service Bus kön. ResourceId används i sin tur för att hämta anslutningssträngen för kön.

iotHubName: Det här fältet är namnet på IoT Hub efter att randomValue har sammanfogats.

storageAccountName: Det här fältet är namnet på lagringskontot efter att randomValue har sammanfogats.

service_bus_namespace: Det här fältet är namnområdet efter att randomValue har sammanfogats.

service_bus_queue: Det här fältet är Service Bus könamnet efter att randomValue har sammanfogats.

sbVersion: Den version av Service Bus API som ska användas. I det här fallet är det "2017-04-01".

Resurser: Storage och container

Den första resursen som skapas är lagringskontot, tillsammans med containern som meddelanden dirigeras till. Containern är en resurs under lagringskontot. Den har en dependsOn -sats för lagringskontot som kräver att lagringskontot skapas före containern.

Så här ser det här avsnittet ut:

{
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[variables('storageAccountName')]",
    "apiVersion": "2018-07-01",
    "location": "[parameters('location')]",
    "sku": {
        "name": "Standard_LRS",
        "tier": "Standard"
    },
    "kind": "Storage",
    "properties": {},
    "resources": [
        {
        "type": "blobServices/containers",
        "apiVersion": "2018-07-01",
        "name": "[concat('default/', parameters('storageContainerName'))]",
        "properties": {
            "publicAccess": "None"
            } ,
        "dependsOn": [
            "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
            ]
        }
    ]
}

Resurser: Service Bus namnområde och kö

Den andra resursen som skapas Service Bus namnområdet, tillsammans med Service Bus som meddelanden dirigeras till. SKU:n är inställd på standard. API-versionen hämtas från variablerna. Det är också inställt på att aktivera Service Bus namnområdet när det här avsnittet distribueras (status:Aktiv).

{
    "type": "Microsoft.ServiceBus/namespaces",
    "comments": "The Sku should be 'Standard' for this tutorial.",
    "sku": {
        "name": "Standard",
        "tier": "Standard"
    },
    "name": "[variables('service_bus_namespace')]",
    "apiVersion": "[variables('sbVersion')]",
    "location": "[parameters('location')]",
    "properties": {
        "provisioningState": "Succeeded",
        "metricId": "[concat('a4295411-5eff-4f81-b77e-276ab1ccda12:', variables('service_bus_namespace'))]",
        "serviceBusEndpoint": "[concat('https://', variables('service_bus_namespace'),'.servicebus.windows.net:443/')]",
        "status": "Active"
    },
    "dependsOn": []
}

Det här avsnittet skapar Service Bus kön. Den här delen av skriptet har dependsOn en -sats som säkerställer att namnområdet skapas före kön.

{
    "type": "Microsoft.ServiceBus/namespaces/queues",
    "name": "[concat(variables('service_bus_namespace'), '/', variables('service_bus_queue'))]",
    "apiVersion": "[variables('sbVersion')]",
    "location": "[parameters('location')]",
    "scale": null,
    "properties": {},
    "dependsOn": [
        "[resourceId('Microsoft.ServiceBus/namespaces', variables('service_bus_namespace'))]"
    ]
}

Resurser: IoT Hub och meddelanderoutning

Nu när lagringskontot och Service Bus-kön har skapats kan du skapa IoT Hub som dirigerar meddelanden till dem. RM-mallen använder satser så att den inte försöker skapa hubben dependsOn innan Service Bus och lagringskontot har skapats.

Här är den första delen av IoT Hub avsnitt. Den här delen av mallen uppsättningar beroenden och börjar med egenskaperna.

{
    "apiVersion": "2018-04-01",
    "type": "Microsoft.Devices/IotHubs",
    "name": "[variables('IoTHubName')]",
    "location": "[parameters('location')]",
    "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]",
        "[resourceId('Microsoft.ServiceBus/namespaces', variables('service_bus_namespace'))]",
        "[resourceId('Microsoft.ServiceBus/namespaces/queues', variables('service_bus_namespace'), variables('service_bus_queue'))]"
    ],
    "properties": {
        "eventHubEndpoints": {}
            "events": {
                "retentionTimeInDays": 1,
                "partitionCount": "[parameters('d2c_partitions')]"
                }
            },

Nästa avsnitt är avsnittet för konfiguration av meddelanderoutning för IoT Hub. Först är avsnittet för slutpunkterna. Den här delen av mallen uppsättningar routningsslutpunkter för Service Bus kön och lagringskontot, inklusive anslutningssträngarna.

För att skapa anslutningssträngen för kön behöver du queueAuthorizationRulesResourcedId, som hämtas infogade. Om du vill skapa anslutningssträngen för lagringskontot hämtar du den primära lagringsnyckeln och använder den sedan i formatet för anslutningssträngen.

Slutpunktskonfigurationen är också den plats där du anger blobformatet AVRO till eller JSON .

"routing": {
   "endpoints": {
       "serviceBusQueues": [
       {
           "connectionString": "[Concat('Endpoint=sb://',variables('service_bus_namespace'),'.servicebus.windows.net/;SharedAccessKeyName=',parameters('AuthRules_sb_queue'),';SharedAccessKey=',listkeys(variables('queueAuthorizationRuleResourceId'),variables('sbVersion')).primaryKey,';EntityPath=',variables('service_bus_queue'))]",
           "name": "[parameters('service_bus_queue_endpoint')]",
           "subscriptionId": "[parameters('subscriptionId')]", 
           "resourceGroup": "[resourceGroup().Name]"
       }
       ],
       "serviceBusTopics": [],
       "eventHubs": [],
       "storageContainers": [
           {
               "connectionString": 
               "[Concat('DefaultEndpointsProtocol=https;AccountName=',variables('storageAccountName'),';AccountKey=',listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), providers('Microsoft.Storage', 'storageAccounts').apiVersions[0]).keys[0].value)]",
               "containerName": "[parameters('storageContainerName')]",
               "fileNameFormat": "{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}",
               "batchFrequencyInSeconds": 100,
               "maxChunkSizeInBytes": 104857600,
               "encoding": "avro",
               "name": "[parameters('storage_endpoint')]",
               "subscriptionId": "[parameters('subscriptionId')]",
               "resourceGroup": "[resourceGroup().Name]"
           }
       ]
   },

Nästa avsnitt är för meddelandevägarna till slutpunkterna. Det finns en konfigurerad för varje slutpunkt, så det finns en för Service Bus och en för lagringskontocontainern.

Kom ihåg att frågevillkoret för meddelanden som dirigeras till lagring är , och att frågevillkoret för meddelanden som level="storage" dirigeras till den Service Bus kön är level="critical" .

"routes": [
    {
        "name": "contosoStorageRoute",
        "source": "DeviceMessages",
        "condition": "level=\"storage\"",
        "endpointNames": [
            "[parameters('storage_endpoint')]"
            ],
        "isEnabled": true
    },
    {
        "name": "contosoSBQueueRoute",
        "source": "DeviceMessages",
        "condition": "level=\"critical\"",
        "endpointNames": [
            "[parameters('service_bus_queue_endpoint')]"
            ],
        "isEnabled": true
    }
],

Den här json-filen visar resten IoT Hub avsnittet, som innehåller standardinformation och SKU:n för hubben.

            "fallbackRoute": {
                "name": "$fallback",
                "source": "DeviceMessages",
                "condition": "true",
                "endpointNames": [
                    "events"
                ],
                "isEnabled": true
            }
        },
        "storageEndpoints": {
            "$default": {
                "sasTtlAsIso8601": "PT1H",
                "connectionString": "",
                "containerName": ""
            }
        },
        "messagingEndpoints": {
            "fileNotifications": {
                "lockDurationAsIso8601": "PT1M",
                "ttlAsIso8601": "PT1H",
                "maxDeliveryCount": 10
            }
        },
        "enableFileUploadNotifications": false,
        "cloudToDevice": {
            "maxDeliveryCount": 10,
            "defaultTtlAsIso8601": "PT1H",
            "feedback": {
                "lockDurationAsIso8601": "PT1M",
                "ttlAsIso8601": "PT1H",
                "maxDeliveryCount": 10
            }
        }
    },
    "sku": {
        "name": "[parameters('sku_name')]",
        "capacity": "[parameters('sku_units')]"
    }
}

Resurser: Service Bus köauktoriseringsregler

Auktoriseringsregeln Service Bus den här kön används för att hämta anslutningssträngen för Service Bus kön. Den använder en dependsOn -sats för att se till att den inte skapas Service Bus den nya namnrymden och Service Bus kön.

{
    "type": "Microsoft.ServiceBus/namespaces/queues/authorizationRules",
    "name": "[concat(variables('service_bus_namespace'), '/', variables('service_bus_queue'), '/', parameters('AuthRules_sb_queue'))]",
    "apiVersion": "[variables('sbVersion')]",
    "location": "[parameters('location')]",
    "scale": null,
    "properties": {
        "rights": [
            "Send"
        ]
    },
    "dependsOn": [
        "[resourceId('Microsoft.ServiceBus/namespaces', variables('service_bus_namespace'))]",
        "[resourceId('Microsoft.ServiceBus/namespaces/queues', variables('service_bus_namespace'), variables('service_bus_queue'))]"
    ]
},

Resurser: Konsumentgrupp

I det här avsnittet skapar du en konsumentgrupp för IoT Hub data som ska användas av Azure Stream Analytics i den andra delen av den här självstudien.

{
    "type": "Microsoft.Devices/IotHubs/eventHubEndpoints/ConsumerGroups",
    "name": "[concat(variables('iotHubName'), '/events/',parameters('consumer_group'))]",
    "apiVersion": "2018-04-01",
    "dependsOn": [
        "[concat('Microsoft.Devices/IotHubs/', variables('iotHubName'))]"
    ]
}

Resurser: Utdata

Om du vill skicka tillbaka ett värde till distributionsskriptet som ska visas använder du ett utdataavsnitt. Den här delen av mallen returnerar anslutningssträngen för Service Bus kön. Att returnera ett värde krävs inte. Det ingår som ett exempel på hur du returnerar resultat till det anropande skriptet.

"outputs": {
    "sbq_connectionString": {
      "type": "string",
      "value": "[Concat('Endpoint=sb://',variables('service_bus_namespace'),'.servicebus.windows.net/;SharedAccessKeyName=',parameters('AuthRules_sb_queue'),';SharedAccessKey=',listkeys(variables('queueAuthorizationRuleResourceId'),variables('sbVersion')).primaryKey,';EntityPath=',variables('service_bus_queue'))]"
    }
  }

Distribuera RM-mallen

Om du vill distribuera mallen till Azure laddar du upp mallen och parameterfilen till Azure Cloud Shell kör sedan ett skript för att distribuera mallen. Öppna Azure Cloud Shell och logga in. I det här exemplet används PowerShell.

Om du vill ladda upp filerna väljer du Upload/Ladda ned filer på menyraden och väljer sedan Upload.

Använd den Utforskaren som visas för att hitta filerna på den lokala disken och välj dem och välj sedan Öppna.

När filerna har laddats upp visas en resultatdialogruta som liknar följande bild.

Filerna laddas upp till resursen som används av din Cloud Shell instans.

Kör skriptet för att utföra distributionen. Den sista raden i det här skriptet hämtar variabeln som har ställts in för att returneras – Service Bus anslutningssträng för kön.

Skriptet anger och använder dessa variabler:

$RGName är resursgruppens namn som mallen ska distribueras till. Det här fältet skapas innan du distribuerar mallen.

$location är den Azure-plats som ska användas för mallen, till exempel "westus".

deploymentname är ett namn som du tilldelar till distributionen för att hämta det returnerade variabelvärdet.

Här är PowerShell-skriptet. Kopiera det här PowerShell-skriptet och klistra in det i Cloud Shell-fönstret och tryck sedan på Retur för att köra det.

$RGName="ContosoResources"
$location = "westus"
$deploymentname="contoso-routing"

# Remove the resource group if it already exists. 
#Remove-AzResourceGroup -name $RGName 
# Create the resource group.
New-AzResourceGroup -name $RGName -Location $location 

# Set a path to the parameter file. 
$parameterFile = "$HOME/template_iothub_parameters.json"
$templateFile = "$HOME/template_iothub.json"

# Deploy the template.
New-AzResourceGroupDeployment `
    -Name $deploymentname `
    -ResourceGroupName $RGName `
    -TemplateParameterFile $parameterFile `
    -TemplateFile $templateFile `
    -verbose

# Get the returning value of the connection string.
(Get-AzResourceGroupDeployment -ResourceGroupName $RGName -Name $deploymentname).Outputs.sbq_connectionString.value

Om du har skriptfel kan du redigera skriptet lokalt, ladda upp det igen till Cloud Shell och köra skriptet igen. När skriptet har körts klart fortsätter du till nästa steg.

Skapa simulerad enhet

Skapa sedan en enhetsidentitet och spara nyckeln för framtida bruk. Den är enhetsidentiteten används av simuleringsprogrammet för att skicka meddelanden till IoT-hubben. Den här funktionen är inte tillgänglig i PowerShell eller när du använder en Azure Resource Manager mall. Följande steg visar hur du skapar den simulerade enheten med hjälp av Azure Portal.

1. Öppna Azure Portal och logga in på ditt Azure-konto.

2. Välj Resursgrupper och välj sedan din resursgrupp. I den här självstudien används ContosoResources.

3. I listan över resurser väljer du din IoT-hubb. I självstudien används ContosoTestHub. Välj IoT-enheter från hubbfönstret.

4. Välj +Lägg till enhet i fönstret IoT-enheter. I rutan Lägg till enhet fyller du i enhets-ID. I den här självstudien används Contoso-Test-Device. Lämna nycklarna tomma och markera Generera nycklar automatiskt. Kontrollera att Connect device to IoT hub (Anslut enhet till IoT-hubb) är aktiverat. Välj Spara.

   

5. Nu när den har skapats väljer du enheten för att se de genererade nycklarna. Välj ikonen Kopiera på primärnyckeln och spara den någonstans, till exempel Anteckningar för testfasen i den här självstudien.

   

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 du har konfigurerat alla resurser och meddelandevägarna har konfigurerats går du vidare till nästa självstudie för att lära dig hur du bearbetar och visar information om de dirigerade meddelandena.