Självstudie: Använda Azure IoT Hub meddelandeberikningar

Meddelande berikanden är möjligheten för Azure IoT Hub att stämpla meddelanden med ytterligare information innan meddelandena skickas till den avsedda slutpunkten. En anledning till att använda meddelandeberikningar är att inkludera data som kan användas för att förenkla nedströmsbearbetning. Om du till exempel utökar enhetsmeddelanden med en tagg för enhetstvillingar kan du minska belastningen på kunder för att göra API-anrop för enhetstvillingar för den här informationen. Mer information finns i Översikt över meddelande berikanden.

I den första delen av den här självstudien såg du hur du skapar anpassade slutpunkter och dirigerar meddelanden till andra Azure-tjänster. I den här självstudien får du se hur du skapar och konfigurerar de extra resurser som behövs för att testa meddelande berikanden för en IoT-hubb. Resurserna innehåller en andra lagringscontainer för ett befintligt lagringskonto (som skapades i den första delen av självstudien) för att lagra berikade meddelanden och en meddelandeväg för att skicka dem dit. När konfigurationerna för meddelandedirigering och meddelandeanrikning har slutförts använder du ett program för att skicka meddelanden till IoT-hubben. Hubben dirigerar dem sedan till båda lagringscontainrarna. Endast de meddelanden som skickas till slutpunkten för den berikade lagringscontainern utökas.

I den här självstudien utför du följande åtgärder:

• Skapa en andra container i ditt lagringskonto.
• Skapa en annan anpassad slutpunkt och dirigera meddelanden till den från IoT-hubben.
• Konfigurera meddelande berikanden som dirigeras till den nya slutpunkten.
• Kör en app som simulerar en IoT-enhet som skickar meddelanden till hubben.
• Visa resultaten och kontrollera att meddelandeberikningarna tillämpas på målmeddelandena.

Förutsättningar

• 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.

• Du måste ha slutfört självstudien: Skicka enhetsdata till Azure Storage med IoT Hub meddelandedirigering och underhålla de resurser som du skapade för den.

• Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här självstudien använder MQTT-protokollet, som kommunicerar över port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

Azure-portalen

Det finns inga andra krav för Azure Portal.

Azure CLI

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att göra det installerar du Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Skapa en andra container i ditt lagringskonto

I den första delen av den här självstudien skapade du ett lagringskonto och en container för dirigerade meddelanden. Nu bör du skapa en andra container för berikade meddelanden.

Azure-portalen

1. I Azure Portal söker du efter Lagringskonton.

2. Välj det konto som du skapade tidigare.

3. I menyn lagringskonto väljer du Containrar i avsnittet Datalagring .

4. Välj Container för att skapa den nya containern.

   

5. Namnge containern enrichedoch välj Skapa.

Azure CLI

Tips

Många av CLI-kommandona som används i den här självstudien använder samma parametrar. För din bekvämlighet har vi dig att definiera lokala variabler som kan anropas efter behov. Se till att köra alla kommandon i samma session, annars måste du omdefiniera variablerna.

Värdena för dessa variabler bör vara för samma resurser som du använde i den första delen av den här självstudien.

1. Definiera variablerna för din IoT-hubb, ditt lagringskonto och din container.

   GROUP_NAME: Ersätt den här platshållaren med namnet på resursgruppen som innehåller din IoT-hubb.

   IOTHUB_NAME: Ersätt den här platshållaren med namnet på din IoT-hubb.

   DEVICE_ID: Ersätt den här platshållaren med enhetens ID.

   STORAGE_NAME: Ersätt den här platshållaren med namnet på ditt lagringskonto.

   I den här självstudien ska värdet för variabeln containerNameutökas.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. Använd kommandot az storage container create för att lägga till containern i ditt lagringskonto.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Dirigera meddelanden till en andra slutpunkt

Skapa en andra slutpunkt och väg för berikade meddelanden.

Azure-portalen

1. I Azure Portal går du till din IoT-hubb.

2. På resursmenyn under Hubbinställningar väljer du Meddelanderoutning och sedan Lägg till.

   

3. På fliken Slutpunkt skapar du en lagringsslutpunkt genom att ange följande information:

   Parameter	Värde
   Slutpunktstyp	Välj Lagring.
   Slutpunktsnamn	Ange ContosoStorageEndpointEnriched.
   Azure Storage-container	Välj Välj en container. Följ anvisningarna för att välja lagringskontot och den berikade container som du skapade i föregående avsnitt.
   Kodning	Välj JSON. Om det här fältet är nedtonat stöder inte din lagringskontoregion JSON. I så fall fortsätter du med standard-AVRO.

   

4. Acceptera standardvärdena för resten av parametrarna och välj Skapa + nästa.

5. Fortsätt att skapa den nya vägen, nu när du har lagt till lagringsslutpunkten. Ange följande information för den nya vägen:

   Parameter	Värde
   Namn	ContosoStorageRouteEnriched
   Datakälla	Kontrollera att Enhetstelemetrimeddelanden har valts i listrutan.
   Aktivera väg	Kontrollera att fältet är inställt på enabled.
   Routningsfråga	Ange level="storage" som frågesträng.

   

6. Välj Skapa + lägg till berikanden.

Azure CLI

1. Konfigurera variablerna för slutpunkts- och vägkommandona så att värdena ContosoStorageEndpointEnriched respektive ContosoStorageRouteEnriched används.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Använd kommandot az iot hub routing-endpoint create för att skapa en anpassad slutpunkt som pekar på lagringscontainern som du skapade i föregående avsnitt.

   az iot hub routing-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --endpoint-resource-group $resourceGroup \
     --endpoint-subscription-id $(az account show --query id -o tsv) \
     --endpoint-type azurestoragecontainer
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Använd kommandot az iot hub route create för att skapa en väg som skickar ett meddelande till level=storage lagringscontainerns slutpunkt.

   az iot hub route create \
     --name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Lägg till meddelandeberikning till den nya slutpunkten

Skapa tre meddelandeberikningar som ska dirigeras till den berikade lagringscontainern .

Azure-portalen

1. På fliken Berikning i guiden Lägg till en väg lägger du till tre meddelandeberikningar för meddelanden som går till slutpunkten för lagringscontainern med namnet enriched.

   Lägg till dessa värden som meddelandeberikningar för Slutpunkten ContosoStorageEndpointEnriched:

   Name	Värde
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (förutsätter att enhetstvillingen har en platstagg)
   Customerid	6ce345b8-1e4a-411e-9398-d34587459a3a

   När du är klar bör dina berikanden se ut ungefär så här:

   

2. Välj Lägg till för att lägga till meddelandeberikningar.

Azure CLI

Gör tre anrop till kommandot az iot hub message-enrichment create för att lägga till meddelandeberikanden till vägen som går till den slutpunkt som skapades tidigare.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Nu har du konfigurerat meddelandeberikningar för alla meddelanden som dirigeras till den slutpunkt som du skapade för berikade meddelanden. Om du inte vill lägga till en platstagg i enhetstvillingen kan du gå vidare till avsnittet Berikning av testmeddelanden för att fortsätta självstudien.

Lägg till platstagg i enhetstvillingen

Ett av de meddelandeberikningar som konfigurerats på din IoT-hubb anger en nyckel för DeviceLocation med dess värde som bestäms av följande sökväg för enhetstvillingen: $twin.tags.location. Om enhetstvillingen inte har någon platstagg stämplas tvillingsökvägen, $twin.tags.location, som en sträng för DeviceLocation-nyckeln i meddelandeberikningarna.

Följ de här stegen för att lägga till en platstagg i enhetens tvilling:

Azure-portalen

1. Gå till din IoT-hubb i Azure Portal.

2. Välj Enheter på navigeringsmenyn i IoT-hubben och välj sedan din enhet.

3. Välj fliken Enhetstvilling längst upp på enhetssidan och lägg till följande rad precis innan den avslutande klammerparentesen längst ned i enhetstvillingen. Välj sedan Spara.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

Använd kommandot az iot hub device-twin update för att uppdatera enhetstvillingen med en ny taggnyckel och ett nytt värde.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Tips

Vänta ungefär fem minuter innan du fortsätter till nästa avsnitt. Det kan ta upp till så lång tid innan uppdateringar av enhetstvillingen återspeglas i meddelandeberikningsvärden.

Mer information om hur enhetstvillingsökvägar hanteras med meddelandeberikningar finns i Begränsningar för meddelandeberikning. Mer information om enhetstvillingar finns i Förstå och använda enhetstvillingar i IoT Hub.

Testa meddelandeberikningar

Nu när meddelandeberikningarna har konfigurerats för Slutpunkten ContosoStorageEndpointEnriched kör du det simulerade enhetsprogrammet för att skicka meddelanden till IoT-hubben. Nu har meddelanderoutning konfigurerats på följande sätt:

• Meddelanden som dirigeras till lagringsslutpunkten som du skapade i den första delen av självstudien utökas inte och lagras i lagringscontainern som du skapade då.

• Meddelanden som dirigeras till lagringsslutpunkten ContosoStorageEndpointEnriched berikas och lagras i lagringscontainern berikad.

Om du inte fortfarande kör konsolprogrammet SimulatedDevice från den första delen av den här självstudien kör du det igen:

Tips

Om du följer Azure CLI-stegen för den här självstudien kör du exempelkoden i en separat session. På så sätt kan du tillåta att exempelkoden fortsätter att köras medan du följer resten av CLI-stegen.

1. Navigera till mappen i exempelmappen /iot-hub/Tutorials/Routing/SimulatedDevice/ .

2. De variabeldefinitioner som du uppdaterade tidigare bör fortfarande vara giltiga, men om de inte är det redigerar du Program.cs dem i filen:

   1. Leta reda på variabeldefinitionerna överst i klassen Program . Uppdatera följande variabler med din egen information:

      • s_myDeviceId: Det enhets-ID som du tilldelade när du registrerade enheten till din IoT-hubb.
      • s_iotHubUri: Värdnamnet för din IoT-hubb, som har formatet IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: Enhetens primärnyckel finns i enhetens identitetsinformation.

   2. Spara och stäng filen.

3. Kör exempelkoden:

   dotnet run
   

När du har lämnat konsolprogrammet för körning i några minuter kan du visa data:

1. Navigera till ditt lagringskonto på Azure-portalen.

2. Välj Storage browser (Lagringswebbläsare ) på navigeringsmenyn. Välj Blobcontainrar för att se de två containrar som du skapade under självstudierna.

   

Meddelandena i containern som kallas enriched har meddelandeberikningar som ingår i meddelandena. Meddelandena i containern som du skapade tidigare har råmeddelanden utan berikning. Öka detaljnivån i den berikade containern tills du kommer längst ned och öppna sedan den senaste meddelandefilen. Gör sedan samma sak för den andra containern för att kontrollera att den ena är berikad och att den ena inte är det.

När du tittar på meddelanden som har berikats bör du se "myIotHub" med hubbnamnet, platsen och kund-ID:t så här:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Rensa resurser

Ta bort alla resurser som du skapade i båda delarna av den här självstudien genom att ta bort resursgruppen. Detta tar även bort alla resurser som ingår i gruppen. Om du inte vill ta bort hela resursgruppen kan du välja enskilda resurser i för att ta bort.

Azure-portalen

1. I Azure Portal går du till den resursgrupp som innehåller IoT-hubben och lagringskontot för den här självstudien.
2. Granska alla resurser som finns i resursgruppen för att avgöra vilka du vill rensa.
   • Om du vill ta bort alla resurser väljer du Ta bort resursgrupp.
   • Om du bara vill ta bort vissa resurser använder du kryssrutorna bredvid varje resursnamn för att markera de som du vill ta bort. Välj sedan Ta bort.

Azure CLI

1. Använd kommandot az resource list för att visa alla resurser i resursgruppen.

   az resource list --resource-group $resourceGroup --output table
   

2. Granska alla resurser som finns i resursgruppen för att avgöra vilka du vill rensa.

   • Om du vill ta bort alla resurser använder du kommandot az group delete .

     az group delete --name $resourceGroup
     

   • Om du bara vill ta bort vissa resurser använder du kommandot az resource delete . Exempel:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Nästa steg

I den här självstudien konfigurerade och testade du meddelandeberikningar för IoT Hub meddelanden när de dirigeras till en slutpunkt.

Mer information om meddelandeberikningar finns i Översikt över meddelandeberikningar.

Om du vill veta mer om IoT Hub fortsätter du till nästa självstudie.

Självstudie: Konfigurera och använda mått och loggar med en IoT-hubb