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å kunderna 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 ser du hur du skapar och konfigurerar de extra resurser som behövs för att testa meddelandeberikningar 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 de berikade meddelandena och en meddelandeväg för att skicka dem dit. När konfigurationerna för meddelandedirigering och meddelande berikanden 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 berikas.

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 meddelandeberikningar 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 skapar du ett kostnadsfritt konto innan du börjar.

• Du måste ha slutfört självstudien: Skicka enhetsdata till Azure Storage med hjälp av IoT Hub-meddelanderoutning 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-protokoll, 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 kringgå det här problemet finns i Anslut ing to IoT Hub (MQTT).

Azure-portalen

Det finns inga andra krav för Azure-portalen.

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 installera 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. Sök efter Lagringskonton i Azure-portalen.

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

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

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

   

5. Ge containern enrichednamnet och välj Skapa.

Azure CLI

Dricks

Många av DE CLI-kommandon som används i den här självstudien använder samma parametrar. För din bekvämlighet vill vi att du definierar 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 ska 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, lagringskonto och 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 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 containerName utö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. Gå till din IoT-hubb i Azure-portalen.

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 Storage.
   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 för att använda värdena ContosoStorageEndpointEnriched respektive ContosoStorageRouteEnriched.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

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

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

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

Lägga 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 berikningar se ut ungefär så här:

   

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

Azure CLI

Gör tre anrop till kommandot az iot hub message-enrichment create för att lägga till meddelandeberikningar till vägen som går till slutpunkten 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 slutpunkten 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

En 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 enhetstvillingsökväg: $twin.tags.location. Om enhetstvillingen inte har någon platstagg stämplas tvillingsökvägen , $twin.tags.locationsom 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-portalen.

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

3. Välj fliken Enhetstvilling längst upp på enhetssidan och lägg till följande rad precis innan det 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"}'

Dricks

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 värden för meddelandeberikning.

Mer information om hur enhetstvillingsökvägar hanteras med meddelande berikanden finns i Begränsningar för meddelande berikanden. 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:

Dricks

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. Gå till mappen i exempelmappen /iot-hub/Tutorials/Routing/SimulatedDevice/ .

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

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

      • s_myDeviceId: Enhets-ID:t som du tilldelade när du registrerade enheten till din IoT-hubb.
      • s_iotHubUri: Värdnamnet för din IoT-hubb, som tar formatet IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: Enhetens primära nyckel som 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 att köras i några minuter kan du visa data:

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

2. Välj 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 berikade har meddelande berikanden som ingår i meddelandena. Meddelandena i containern som du skapade tidigare har råmeddelandena 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

Om du vill ta bort alla resurser som du skapade i båda delarna av den här självstudien tar du 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 inom för att ta bort.

Azure-portalen

1. I Azure-portalen 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 som du vill rensa.
   • Om du vill ta bort alla resurser väljer du Ta bort resursgrupp.
   • Om du bara vill ta bort en viss resurs 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 som 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 . Till 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 meddelande berikanden finns i Översikt över meddelande berikanden.

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