Esercitazione: Usare gli arricchimenti dei messaggi dell'hub IoT di Azure

Gli Arricchimenti di messaggi sono la capacità dell'hub IoT di Azure di stampare i messaggi con informazioni aggiuntive prima che vengano inviati all'endpoint designato. Un motivo per usare gli arricchimenti dei messaggi consiste nell'includere dati che possono essere usati per semplificare l'elaborazione downstream. Ad esempio, l'arricchimento dei messaggi dei dispositivi con un tag del dispositivo gemello può ridurre il carico dei clienti per effettuare chiamate all'API del dispositivo gemello per ottenere queste informazioni. Per altre informazioni, vedere Panoramica degli arricchimenti dei messaggi.

Nella prima parte di questa esercitazione si è visto come creare endpoint personalizzati e instradare i messaggi verso altri servizi Azure. In questa esercitazione viene illustrato come creare e configurare le risorse aggiuntive necessarie per testare gli arricchimenti dei messaggi per un hub IoT. Le risorse includono un secondo contenitore di archiviazione per un account di archiviazione esistente (creato nella prima parte dell'esercitazione) per contenere i messaggi arricchiti e una route di messaggi per inviarli. Al termine delle configurazioni per il routing dei messaggi e gli arricchimenti dei messaggi, si usa un'applicazione per inviare messaggi all'hub IoT. L'hub li indirizza quindi a entrambi i contenitori di archiviazione. Vengono arricchiti solo i messaggi inviati all'endpoint per il contenitore di archiviazione arricchito.

In questa esercitazione si eseguono le seguenti attività:

• Creare un secondo contenitore nell'account di archiviazione.
• Creare un altro endpoint personalizzato e instradare i messaggi dall'hub IoT.
• Configurare gli arricchimenti dei messaggi che vengono indirizzati al nuovo endpoint.
• Eseguire un'app che simula un dispositivo IoT che invia messaggi all'hub.
• Visualizzare i risultati e verificare che gli arricchimenti dei messaggi vengano applicati ai messaggi di destinazione.

Prerequisiti

• È necessario disporre di una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

• È necessario aver completato l'Esercitazione: Inviare i dati dei dispositivi ad Archiviazione di Azure usando il routing dei messaggi dell'hub IoT e mantenere le risorse create a tale scopo.

• Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questa esercitazione usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Azure portal

Non esistono altri prerequisiti per il portale di Azure.

Interfaccia della riga di comando di Azure

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

  

• Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

  • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.

  • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Creare un secondo contenitore nell'account di archiviazione

Nella prima parte di questa esercitazione è stato creato un account di archiviazione e un contenitore per i messaggi indirizzati. Ora è necessario creare un secondo contenitore per i messaggi arricchiti.

Azure portal

1. Nel portale di Azure, cercare Account di archiviazione.

2. Selezionare l'account creato in precedenza.

3. Nel menu dell'account di archiviazione, selezionare Contenitori dalla sezione Archiviazione dati.

4. Selezionare Contenitore per creare il nuovo contenitore.

   

5. Assegnare un nome al contenitore enriched e selezionare Crea.

Interfaccia della riga di comando di Azure

Suggerimento

Molti comandi dell'interfaccia della riga di comando usati in questa esercitazione usano gli stessi parametri. Per comodità, sono definite variabili locali che possono essere chiamate in base alle esigenze. Assicurarsi di eseguire tutti i comandi nella stessa sessione, altrimenti sarà necessario ridefinire le variabili.

I valori di queste variabili devono essere quelli delle stesse risorse usate nella prima parte di questa esercitazione.

1. Definire le variabili per l'hub IoT, l'account di archiviazione e il contenitore.

   GROUP_NAME: sostituire questo segnaposto con il nome del gruppo di risorse che contiene l'hub IoT.

   IOTHUB_NAME: sostituire questo segnaposto con il nome dell'hub IoT.

   DEVICE_ID: sostituire questo segnaposto con l'ID del dispositivo.

   STORAGE_NAME: sostituire questo segnaposto con il nome dell'account di archiviazione.

   Per questa esercitazione, il valore della variabile containerName deve essere arricchito.

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

2. Usare il comando az storage container create per aggiungere il contenitore all'account di archiviazione.

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

Indirizzare i messaggi a un secondo endpoint

Creare un secondo endpoint e una route per i messaggi arricchiti.

Importante

Questo articolo include la procedura per connettersi a un servizio usando una firma di accesso condiviso. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione a un servizio con Microsoft Entra ID o identità gestite rappresenta un approccio più sicuro. Per altre informazioni, vedere Procedure consigliate per la sicurezza > Sicurezza cloud.

Azure portal

1. Nel portale di Azure passare all'hub IoT.

2. Nel menu delle risorse in Impostazioni hub, selezionare Routing messaggi e quindi selezionare Aggiungi.

   

3. Nella scheda Endpoint, creare un endpoint di archiviazione specificando le informazioni seguenti:

   Parametro	Valore
   Tipo di endpoint	Selezionare Archiviazione.
   Nome endpoint	Immetti ContosoStorageEndpointEnriched.
   Contenitore di Archiviazione di Azure	Scegliere Selezionare un contenitore. Seguire le istruzioni per selezionare l'account di archiviazione e il contenitore arricchito creato nella sezione precedente.
   Encoding	Selezionare JSON. Se questo campo è disattivato, l'area dell'account di archiviazione non supporta JSON. In tal caso, continuare con l'impostazione AVRO predefinita.

   

4. Accettare i valori predefiniti per il resto dei parametri e selezionare Crea + Successivo.

5. Continuare a creare la nuova route, dopo aver aggiunto l'endpoint di archiviazione. Specificare le informazioni seguenti per la nuova route:

   Parametro	valore
   Nome	ContosoStorageRouteEnriched
   Origine dati	Assicurarsi che sia selezionato Messaggi di telemetria dispositivo nell'elenco a discesa.
   Abilita route	Verificare che questo campo sia impostato su enabled.
   Query di routing	immettere level="storage" come stringa di query.

   

6. Selezionare Crea e aggiungi arricchimenti.

Interfaccia della riga di comando di Azure

1. Configurare le variabili per i comandi endpoint e route in modo che usino rispettivamente i valori ContosoStorageEndpointEnriched e ContosoStorageRouteEnriched..

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Usare il comando az iot hub message-endpoint create per creare un endpoint personalizzato che punti al contenitore di archiviazione creato nella sezione precedente.

   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. Usare il comando az iot hub message-route create per creare una route che passi qualsiasi messaggio dove level=storage per l'endpoint del contenitore di archiviazione.

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

Aggiungere l'arricchimento dei messaggi al nuovo endpoint

Creare tre arricchimenti di messaggi che verranno indirizzati al contenitore di archiviazione arricchito.

Azure portal

1. Nella scheda Arricchimento della procedura guidata Aggiungi una route, aggiungere tre arricchimenti dei messaggi per i messaggi diretti all'endpoint per il contenitore di archiviazione denominato arricchito.

   Aggiungere questi valori come arricchimenti dei messaggi per l'endpoint ContosoStorageEndpointEnriched:

   Nome	Valore
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (presuppone che il dispositivo gemello abbia un tag di posizione)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Al termine, gli arricchimenti dovrebbero avere un aspetto simile a questa immagine:

   

2. Selezionare Aggiungi per aggiungere gli arricchimenti dei messaggi.

Interfaccia della riga di comando di Azure

Effettuare tre chiamate al comando az iot hub message-enrichment create per aggiungere arricchimenti di messaggi alla route diretta all'endpoint creato in precedenza.

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

Sono ora stati configurati gli arricchimenti dei messaggi per tutti i messaggi indirizzati all'endpoint creato per i messaggi arricchiti. Se non si vuole aggiungere un tag di posizione al dispositivo gemello, si può passare alla sezione Test degli arricchimenti dei messaggi per continuare l'esercitazione.

Aggiungere il tag di posizione al dispositivo gemello

Uno degli arricchimenti dei messaggi configurati nell'hub IoT specifica una chiave di DeviceLocation con il relativo valore determinato dal percorso del dispositivo gemello seguente: $twin.tags.location. Se il dispositivo gemello non ha un tag di posizione, il percorso del dispositivo gemello, $twin.tags.location, verrà stampato come stringa per la chiave DeviceLocation negli arricchimenti dei messaggi.

Seguire questa procedura per aggiungere un tag di posizione al dispositivo gemello:

Azure portal

1. Passare all'hub IoT nel portale di Azure.

2. Selezionare Dispositivi nel menu di spostamento dell'hub IoT, quindi selezionare il dispositivo.

3. Selezionare la scheda Dispositivo gemello nella parte superiore della pagina del dispositivo e aggiungere la riga seguente subito prima della parentesi graffa di chiusura nella parte inferiore del dispositivo gemello. Quindi selezionare Salva.

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

   

Interfaccia della riga di comando di Azure

Usare il comando az iot hub device-twin update per aggiornare il dispositivo gemello con una nuova chiave e un nuovo valore di tag.

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

Suggerimento

Attendere circa cinque minuti prima di passare alla sezione successiva. Gli aggiornamenti al dispositivo gemello possono richiedere fino a tale periodo di tempo prima di avere effetto sui valori di arricchimento dei messaggi.

Per altre informazioni sulla gestione dei percorsi dei dispositivi gemelli con arricchimenti dei messaggi, vedere Limitazioni degli arricchimenti dei messaggi. Per altre informazioni sui dispositivi gemelli, vedere Comprendere e usare dispositivi gemelli nell'hub IoT.

Testare gli arricchimenti dei messaggi

Ora che gli arricchimenti dei messaggi sono configurati per l'endpoint ContosoStorageEndpointEnriched, eseguire l'applicazione del dispositivo simulato per inviare messaggi all'hub IoT. A questo punto, il routing dei messaggi è stato configurato come segue:

• I messaggi indirizzati all'endpoint di archiviazione creato nella prima parte dell'esercitazione non verranno arricchiti e verranno archiviati nel contenitore di archiviazione creato in quel momento.

• I messaggi indirizzati all'endpoint di archiviazione ContosoStorageEndpointEnriched verranno arricchiti e archiviati nel contenitore di archiviazione arricchiti.

Se l'applicazione della console SimulatedDevice non è ancora in esecuzione dalla prima parte di questa esercitazione, eseguirla di nuovo:

Suggerimento

Se si seguono i passaggi dell'interfaccia della riga di comando di Azure per questa esercitazione, eseguire il codice di esempio in una sessione separata. In questo modo è possibile consentire al codice di esempio di continuare l'esecuzione mentre si seguono i passaggi rimanenti dell'interfaccia della riga di comando.

1. Nella cartella di esempio passare alla cartella /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Le definizioni delle variabili aggiornate in precedenza dovrebbero essere ancora valide; in caso contrario, modificarle nel file Program.cs:

   1. Trova le definizioni delle variabili all'inizio della classe Programma. Aggiornare le variabili seguenti con le proprie informazioni:

      • s_myDeviceId: ID dispositivo assegnato durante la registrazione del dispositivo nell'hub IoT.
      • s_iotHubUri: nome host dell'hub IoT, che accetta il formato IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: chiave primaria del dispositivo presente nelle informazioni sull'identità del dispositivo.

   2. Salva e chiudi il file.

3. Eseguire il codice di esempio:

   dotnet run
   

Dopo aver lasciato l'applicazione console in esecuzione per alcuni minuti, visualizzare i dati:

1. Nel portale di Azure passare all'account di archiviazione.

2. Selezionare Browser di archiviazione dal menu di spostamento. Selezionare Contenitori BLOB per visualizzare i due contenitori creati durante le esercitazioni.

   

I messaggi nel contenitore chiamato arricchiti hanno gli arricchimenti dei messaggi inclusi nei messaggi. I messaggi nel contenitore creati in precedenza hanno i messaggi non elaborati senza arricchimenti. Eseguire il drill-down nel contenitore arricchiti fino al fondo, quindi aprire il file del messaggio più recente. Poi fare lo stesso per l'altro contenitore per verificare che uno sia arricchito e l'altro no.

Quando si analizzano i messaggi che sono stati arricchiti, si dovrebbe visualizzare "myIotHub" con il nome dell'hub, la posizione e l'ID cliente, come in questo caso:

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

Pulire le risorse

Per rimuovere tutte le risorse create in entrambe le parti di questa esercitazione, eliminare il gruppo di risorse. Questa azione elimina tutte le risorse contenute all'interno del gruppo. Se non si vuole eliminare l'intero gruppo di risorse, è possibile selezionare le singole risorse da eliminare.

Azure portal

1. Nel portale di Azure, passare al gruppo di risorse che contiene l'hub IoT e l'account di archiviazione per questa esercitazione.
2. Rivedere tutte le risorse presenti nel gruppo di risorse per determinare quali risorse pulire.
   • Se si desidera eliminare tutte le risorse, selezionare Elimina gruppo di risorse.
   • Se si desidera eliminare solo una determinata risorsa, usare le caselle di controllo accanto al nome di ogni risorsa per selezionare quelle da eliminare. Quindi seleziona Elimina.

Interfaccia della riga di comando di Azure

1. Usare il comando az resource list per visualizzare tutte le risorse nel gruppo di risorse.

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

2. Rivedere tutte le risorse presenti nel gruppo di risorse per determinare quali risorse pulire.

   • Se si desidera eliminare tutte le risorse, usare il comando az group delete.

     az group delete --name $resourceGroup
     

   • Se si desidera eliminare solo determinate risorse, usare il comando az resource delete. Ad esempio:

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

Passaggi successivi

In questa esercitazione sono stati configurati e testati gli arricchimenti dei messaggi per i messaggi dell'hub IoT mentre vengono indirizzati a un endpoint.

Per altre informazioni sugli arricchimenti dei messaggi, vedere Panoramica degli arricchimenti dei messaggi.

Per altre informazioni sull'hub IoT, passare all'esercitazione successiva.

Esercitazione: Configurare e usare metriche e log con un hub IoT