Zelfstudie: Azure IoT Hub-berichtverrijkingen gebruiken

Berichtverrijkingen zijn de mogelijkheid van Azure IoT Hub om berichten te stempelen met aanvullende informatie voordat de berichten naar het aangewezen eindpunt worden verzonden. Een van de redenen voor het gebruik van berichtverrijkingen is het opnemen van gegevens die kunnen worden gebruikt om downstreamverwerking te vereenvoudigen. Het verrijken van apparaatberichten met een apparaatdubbeltag kan bijvoorbeeld de belasting voor klanten verminderen om API-aanroepen van apparaatdubbels te maken voor deze informatie. 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 kunt maken en configureren 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 berichtverrijkingen zijn voltooid, gebruikt u een toepassing om berichten naar de IoT-hub te verzenden. De hub stuurt ze vervolgens 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 een ander aangepast eindpunt en routeer berichten naar het eindpunt vanuit de IoT-hub.
• Configureer berichtverrijkingen die naar het nieuwe eindpunt worden gerouteerd.
• Voer een app uit die een IoT-apparaat simuleert 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 geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

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

• Zorg ervoor dat de poort 8883 is geopend in uw 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 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 gerouteerde berichten. Nu moet u een tweede container maken voor verrijkte berichten.

Azure-portal

1. Zoek in Azure Portal naar Opslagaccounts.

2. Selecteer het account dat u eerder hebt gemaakt.

3. Selecteer Containers in het menu opslagaccount in de sectie Gegevensopslag.

4. Selecteer Container om de nieuwe container te maken.

   

5. Geef de container enrichedeen naam en selecteer Maken.

Azure-CLI

Tip

Veel van de CLI-opdrachten die in deze zelfstudie worden gebruikt, gebruiken dezelfde parameters. Voor uw gemak definiëren we lokale variabelen die naar behoefte 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 zijn voor dezelfde resources 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.

   Azure CLI

   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.

   Azure CLI

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

Berichten routeren naar een tweede eindpunt

Maak een tweede eindpunt en route voor de verrijkte berichten.

Belangrijk

Dit artikel bevat stappen voor het maken van verbinding met een service met behulp van een handtekening voor gedeelde toegang. Deze verificatiemethode is handig voor testen en evalueren, maar verificatie bij een service met Microsoft Entra ID of beheerde identiteiten is een veiligere benadering. Zie Best practices > voor beveiliging voor cloudbeveiliging voor meer informatie.

Azure-portal

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

2. Selecteer in het resourcemenu onder Hub-instellingen de optie Berichtroutering en selecteer Vervolgens Toevoegen.

   

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

   Parameter	Weergegeven als
   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. In dat geval gaat u 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	Weergegeven als
   Naam	ContosoStorageRouteEnriched
   Gegevensbron	Controleer of Apparaattelemetrieberichten is geselecteerd in de vervolgkeuzelijst.
   Route inschakelen	Controleer of dit veld is ingesteld op enabled.
   Routeringsquery	Voer level="storage" in als querytekenreeks.

   

6. Selecteer Verrijkingen maken en toevoegen.

Azure-CLI

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

   Azure CLI

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

   Azure CLI

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

   Azure CLI

   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"'
   

Berichtverrijking toevoegen aan het nieuwe eindpunt

Maak drie berichtverrijkingen die worden gerouteerd 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 verrijkt.

   Voeg deze waarden toe als berichtverrijkingen voor het eindpunt ContosoStorageEndpointEnriched:

   Naam	Weergegeven als
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (gaat ervan uit dat de apparaatdubbel een locatietag heeft)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Wanneer u klaar bent, moeten uw verrijkingen er ongeveer als volgt uitzien:

   

2. Selecteer Toevoegen om de berichtverrijkingen toe te voegen.

Azure-CLI

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

Azure CLI

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 hebt gemaakt voor verrijkte berichten. 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 op uw IoT-hub zijn geconfigureerd, geeft een sleutel van DeviceLocation op met de waarde 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, als een tekenreeks voor de DeviceLocation-sleutel in de berichtverrijkingen gestempeld.

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

Azure-portal

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

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

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

   JSON

     , "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.

Azure CLI

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 die tijd duren voordat updates van 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 vervolgens hebt gemaakt.

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

Als u de SimulatedDevice-consoletoepassing nog niet uitvoert vanuit het eerste deel van deze zelfstudie, 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 variabelendefinities die u eerder hebt bijgewerkt, moeten nog steeds geldig zijn, maar zo niet, bewerk 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.netgebruikt.
      • s_deviceKey: de primaire sleutel van het apparaat in de apparaat-id-gegevens.

   2. Sla het bestand op en sluit het bestand.

3. Voer de voorbeeldcode uit:

   Console

   dotnet run
   

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

1. Ga in Azure Portal naar uw opslagaccount.

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

   

De berichten in de container met de naam 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 komt en open vervolgens het meest recente berichtbestand. Doe hetzelfde voor de andere container om te controleren of de ene is verrijkt en niet.

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

JSON

{
  "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 de hele resourcegroep niet wilt verwijderen, kunt u afzonderlijke resources selecteren die u wilt verwijderen.

Azure-portal

1. Navigeer in Azure Portal naar de resourcegroep met het IoT-hub- en opslagaccount voor deze zelfstudie.
2. Bekijk 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 resources te selecteren die u wilt verwijderen. Selecteer daarna Verwijderen.

Azure-CLI

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

   Azure CLI

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

2. Bekijk 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 .

     Azure CLI

     az group delete --name $resourceGroup
     

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

     Azure CLI

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

Volgende stappen

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

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