Zelfstudie: Berichtverrijkingen Azure IoT Hub gebruiken

Berichtverrijkingen zijn de mogelijkheid van Azure IoT Hub om berichten te voorzien van een stempel met aanvullende informatie voordat de berichten naar het aangewezen eindpunt worden verzonden. Een reden om berichtverrijkingen te gebruiken, is om gegevens op te nemen die kunnen worden gebruikt om downstreamverwerking te vereenvoudigen. Het verrijken van apparaatberichten met een tag van een apparaatdubbel kan bijvoorbeeld de belasting van klanten verminderen om api-aanroepen van apparaatdubbels voor deze informatie te maken. Zie Overzicht van berichtverrijkingen voor meer informatie.

In het eerste deel van deze zelfstudie hebt u gezien hoe u aangepaste eindpunten kunt maken en berichten kunt routeren naar andere Azure-services. In deze zelfstudie ziet u hoe u de extra resources maakt en configureert die nodig zijn om berichtverrijkingen voor een IoT-hub te testen. De resources bevatten een tweede opslagcontainer voor een bestaand opslagaccount (gemaakt in het eerste deel van de zelfstudie) voor het opslaan van de verrijkte berichten en een berichtroute om ze daarheen te verzenden. Nadat de configuraties voor de berichtroutering en berichtverrijking zijn voltooid, gebruikt u een toepassing om berichten naar de IoT-hub te verzenden. De hub stuurt deze vervolgens door naar beide opslagcontainers. Alleen de berichten die naar het eindpunt voor de verrijkte opslagcontainer worden verzonden, worden verrijkt.

In deze zelfstudie voert u de volgende taken uit:

• Maak een tweede container in uw opslagaccount.
• Maak nog een aangepast eindpunt en routeer berichten ernaar vanuit de IoT-hub.
• Configureer berichtverrijkingen die worden doorgestuurd naar het nieuwe eindpunt.
• Voer een app uit waarmee een IoT-apparaat wordt gesimuleerd dat berichten naar de hub verzendt.
• Bekijk de resultaten en controleer of de berichtverrijkingen worden toegepast op de doelberichten.

Vereisten

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

• U moet de zelfstudie Apparaatgegevens verzenden naar Azure Storage met behulp van IoT Hub berichtroutering hebben voltooid en de resources hebben onderhouden die u ervoor hebt gemaakt.

• Zorg ervoor dat de poort 8883 is geopend in de firewall. In het apparaatvoorbeeld 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-portal

Er zijn geen andere vereisten voor de Azure Portal.

Azure-CLI

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht AZ login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Een tweede container maken in uw opslagaccount

In het eerste deel van deze zelfstudie hebt u een opslagaccount en container gemaakt voor doorgestuurde berichten. Maak nu een tweede container voor verrijkte berichten.

Azure-portal

1. Zoek in de Azure Portal naar Opslagaccounts.

2. Selecteer het account dat u eerder hebt gemaakt.

3. Selecteer containers in het menu van het opslagaccount in de sectie Gegevensopslag .

4. Selecteer Container om de nieuwe container te maken.

   

5. Noem de container enricheden selecteer Maken.

Azure-CLI

Tip

Veel van de CLI-opdrachten die in deze zelfstudie worden gebruikt, gebruiken dezelfde parameters. Voor uw gemak laten we u lokale variabelen definiëren die indien nodig kunnen worden aangeroepen. Zorg ervoor dat u alle opdrachten in dezelfde sessie uitvoert, anders moet u de variabelen opnieuw definiëren.

De waarden voor deze variabelen moeten voor dezelfde resources zijn die u in het eerste deel van deze zelfstudie hebt gebruikt.

1. Definieer de variabelen voor uw IoT-hub, opslagaccount en container.

   GROUP_NAME: vervang deze tijdelijke aanduiding door de naam van de resourcegroep die uw IoT-hub bevat.

   IOTHUB_NAME: vervang deze tijdelijke aanduiding door de naam van uw IoT-hub.

   DEVICE_ID: vervang deze tijdelijke aanduiding door de id van uw apparaat.

   STORAGE_NAME: vervang deze tijdelijke aanduiding door de naam van uw opslagaccount.

   Voor deze zelfstudie moet de waarde voor de containerName variabele worden verrijkt.

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

2. Gebruik de opdracht az storage container create om de container toe te voegen aan uw opslagaccount.

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

Berichten doorsturen naar een tweede eindpunt

Maak een tweede eindpunt en route voor de verrijkte berichten.

Azure-portal

1. Ga in de Azure Portal naar uw IoT-hub.

2. Selecteer in het resourcemenu onder Hubinstellingende optie Berichtroutering en selecteer vervolgens Toevoegen.

   

3. Maak op het tabblad Eindpunt een opslageindpunt door de volgende informatie op te geven:

   Parameter	Waarde
   Eindpunttype	Selecteer Opslag.
   Eindpuntnaam	Voer ContosoStorageEndpointEnriched in.
   Azure Storage-container	Selecteer Een container kiezen. Volg de aanwijzingen om het opslagaccount en de verrijkte container te selecteren die u in de vorige sectie hebt gemaakt.
   Codering	Selecteer JSON. Als dit veld grijs wordt weergegeven, biedt uw opslagaccountregio geen ondersteuning voor JSON. Ga in dat geval verder met de standaard AVRO.

   

4. Accepteer de standaardwaarden voor de rest van de parameters en selecteer Maken + volgende.

5. Ga door met het maken van de nieuwe route, nu u het opslageindpunt hebt toegevoegd. Geef de volgende informatie op voor de nieuwe route:

   Parameter	Waarde
   Naam	ContosoStorageRouteEnriched
   Gegevensbron	Controleer of Telemetrieberichten voor apparaten is geselecteerd in de vervolgkeuzelijst.
   Route inschakelen	Controleer of dit veld is ingesteld op enabled.
   Routeringsquery	Voer level="storage" in als querytekenreeks.

   

6. Selecteer Maken en verrijkingen toevoegen.

Azure-CLI

1. Configureer de variabelen voor de eindpunt- en routeopdrachten om respectievelijk de waarden ContosoStorageEndpointEnriched en ContosoStorageRouteEnriched te gebruiken.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Gebruik de opdracht az iot hub routing-endpoint create om een aangepast eindpunt te maken dat verwijst naar de opslagcontainer die u in de vorige sectie hebt gemaakt.

   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. Gebruik de opdracht az iot hub route create om een route te maken die een bericht waar level=storage doorgeeft aan het eindpunt van de opslagcontainer.

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

Berichtverrijking toevoegen aan het nieuwe eindpunt

Maak drie berichtverrijkingen die worden doorgestuurd naar de verrijkte opslagcontainer.

Azure-portal

1. Voeg op het tabblad Verrijking van de wizard Een route toevoegen drie berichtverrijkingen toe voor de berichten die naar het eindpunt gaan voor de opslagcontainer met de naam enriched.

   Voeg deze waarden toe als berichtverrijkingen voor het eindpunt ContosoStorageEndpointEnriched:

   Naam	Waarde
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (wordt ervan uitgegaan dat de apparaatdubbel een locatietag heeft)
   Klantid	6ce345b8-1e4a-411e-9398-d34587459a3a

   Wanneer u klaar bent, moeten uw verrijkingen er ongeveer uitzien als in deze afbeelding:

   

2. Selecteer Toevoegen om de berichtverrijkingen toe te voegen.

Azure-CLI

Voer drie aanroepen naar de opdracht az iot hub message-enrichment create om berichtverrijkingen toe te voegen aan de route die naar het eerder gemaakte eindpunt gaat.

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

U hebt nu berichtverrijkingen ingesteld voor alle berichten die worden doorgestuurd naar het eindpunt dat u voor verrijkte berichten hebt gemaakt. Als u geen locatietag wilt toevoegen aan de apparaatdubbel, kunt u doorgaan naar de sectie Berichtverrijkingen testen om door te gaan met de zelfstudie.

Locatietag toevoegen aan de apparaatdubbel

Een van de berichtverrijkingen die zijn geconfigureerd op uw IoT-hub, geeft een sleutel van DeviceLocation op met de waarde ervan die wordt bepaald door het volgende pad naar de apparaatdubbel: $twin.tags.location. Als uw apparaatdubbel geen locatietag heeft, wordt het dubbelpad, $twin.tags.location, gestempeld als een tekenreeks voor de DeviceLocation-sleutel in de berichtverrijkingen.

Volg deze stappen om een locatietag toe te voegen aan de dubbel van uw apparaat:

Azure-portal

1. Navigeer naar uw IoT-hub in de Azure Portal.

2. Selecteer Apparaten in het navigatiemenu van de IoT-hub en selecteer vervolgens uw apparaat.

3. Selecteer het tabblad Apparaatdubbel bovenaan de apparaatpagina en voeg de volgende regel toe vlak voor de afsluitende accolade onder aan de apparaatdubbel. Selecteer vervolgens Opslaan.

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

   

Azure-CLI

Gebruik de opdracht az iot hub device-twin update om de apparaatdubbel bij te werken met een nieuwe tagsleutel en -waarde.

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

Tip

Wacht ongeveer vijf minuten voordat u verdergaat met de volgende sectie. Het kan tot zo lang duren voordat updates voor de apparaatdubbel worden weergegeven in berichtverrijkingswaarden.

Zie Beperkingen voor berichtverrijkingen voor meer informatie over hoe apparaatdubbelpaden worden verwerkt met berichtverrijkingen. Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie over apparaatdubbels.

Verrijkingen van testberichten

Nu de berichtverrijkingen zijn geconfigureerd voor het eindpunt ContosoStorageEndpointEnriched , voert u de toepassing voor het gesimuleerde apparaat uit om berichten naar de IoT-hub te verzenden. Op dit moment is berichtroutering als volgt ingesteld:

• Berichten die worden doorgestuurd naar het opslageindpunt dat u in het eerste deel van de zelfstudie hebt gemaakt, worden niet verrijkt en worden opgeslagen in de opslagcontainer die u toen hebt gemaakt.

• Berichten die worden doorgestuurd naar het opslageindpunt ContosoStorageEndpointEnriched , worden verrijkt en opgeslagen in de opslagcontainer verrijkt.

Als u de SimulatedDevice-consoletoepassing uit het eerste deel van deze zelfstudie nog niet uitvoert, voert u deze opnieuw uit:

Tip

Als u de Azure CLI-stappen voor deze zelfstudie volgt, voert u de voorbeeldcode uit in een afzonderlijke sessie. Op die manier kunt u toestaan dat de voorbeeldcode wordt uitgevoerd terwijl u de rest van de CLI-stappen volgt.

1. Navigeer in de voorbeeldmap naar de /iot-hub/Tutorials/Routing/SimulatedDevice/ map.

2. De variabeledefinities die u eerder hebt bijgewerkt, moeten nog steeds geldig zijn, maar als dat niet het geval is, bewerkt u ze in het Program.cs bestand:

   1. Zoek de variabeledefinities boven aan de klasse Program . Werk de volgende variabelen bij met uw eigen gegevens:

      • s_myDeviceId: de apparaat-id die u hebt toegewezen bij het registreren van het apparaat bij uw IoT-hub.
      • s_iotHubUri: de hostnaam van uw IoT-hub, die de indeling IOTHUB_NAME.azure-devices.netheeft.
      • s_deviceKey: de primaire sleutel van het apparaat die is gevonden in de identiteitsgegevens van het apparaat.

   2. Sla het bestand op en sluit het.

3. Voer de voorbeeldcode uit:

   dotnet run
   

Nadat u de consoletoepassing een paar minuten hebt laten uitvoeren, bekijkt u de gegevens:

1. Ga in Azure Portal naar uw opslagaccount.

2. Selecteer Opslagbrowser in het navigatiemenu. Selecteer Blobcontainers om de twee containers te zien die u in de loop van deze zelfstudies hebt gemaakt.

   

De berichten in de container verrijkt hebben de berichtverrijkingen opgenomen in de berichten. De berichten in de container die u eerder hebt gemaakt, bevatten de onbewerkte berichten zonder verrijkingen. Zoom in op de verrijkte container totdat u onderaan bent en open vervolgens het meest recente berichtbestand. Doe vervolgens hetzelfde voor de andere container om te controleren of de ene is verrijkt en de andere niet.

Wanneer u berichten bekijkt die zijn verrijkt, ziet "myIotHub" u als volgt de hubnaam, de locatie en de klant-id:

{
  "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"
}

Resources opschonen

Als u alle resources wilt verwijderen die u in beide delen van deze zelfstudie hebt gemaakt, verwijdert u de resourcegroep. Hiermee verwijdert u ook alle resources in de groep. Als u niet de hele resourcegroep wilt verwijderen, kunt u afzonderlijke resources binnen selecteren om te verwijderen.

Azure-portal

1. Navigeer in de Azure Portal naar de resourcegroep die de IoT-hub en het opslagaccount voor deze zelfstudie bevat.
2. Controleer alle resources in de resourcegroep om te bepalen welke u wilt opschonen.
   • Als u alle resources wilt verwijderen, selecteert u Resourcegroep verwijderen.
   • Als u alleen bepaalde resources wilt verwijderen, gebruikt u de selectievakjes naast elke resourcenaam om de resourcenamen te selecteren die u wilt verwijderen. Selecteer vervolgens Verwijderen.

Azure-CLI

1. Gebruik de opdracht az resource list om alle resources in uw resourcegroep weer te geven.

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

2. Controleer alle resources in de resourcegroep om te bepalen welke u wilt opschonen.

   • Als u alle resources wilt verwijderen, gebruikt u de opdracht az group delete .

     az group delete --name $resourceGroup
     

   • Als u alleen bepaalde resources wilt verwijderen, gebruikt u de opdracht az resource delete . Bijvoorbeeld:

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

Volgende stappen

In deze zelfstudie hebt u berichtverrijkingen geconfigureerd en getest voor IoT Hub berichten die naar een eindpunt worden gerouteerd.

Zie Overzicht van berichtverrijkingen voor meer informatie over berichtverrijkingen.

Ga verder met de volgende zelfstudie voor meer informatie over IoT Hub.

Zelfstudie: Metrische gegevens en logboeken instellen en gebruiken met een IoT-hub