Esercitazione: Usare hub IoT di Azure arricchimenti dei messaggi

Gli arricchimenti dei messaggi sono la possibilità di hub IoT di Azure di stampare i messaggi con informazioni aggiuntive prima che i messaggi 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 di dispositivo gemello può ridurre il carico nei clienti per effettuare chiamate API di dispositivo gemello per queste informazioni. Per altre informazioni, vedere Panoramica degli arricchimenti dei messaggi.

Nella prima parte di questa esercitazione è stato illustrato come creare endpoint personalizzati e instradare messaggi ad altri servizi di 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 instrada quindi a entrambi i contenitori di archiviazione. Vengono arricchiti solo i messaggi inviati all'endpoint per il contenitore di archiviazione arricchita .

In questa esercitazione si eseguono le seguenti attività:

• Creare un secondo contenitore nell'account di archiviazione.
• Creare un altro endpoint personalizzato e indirizzare i messaggi dall'hub IoT.
• Configurare gli arricchimenti dei messaggi 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.

• Esercitazione completata: inviare i dati del dispositivo ad Archiviazione di Azure usando hub IoT routing dei messaggi e mantenere le risorse create.

• 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 per 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 con l'interfaccia della riga di comando di Azure.

  • Quando viene richiesto, installare l'estensione dell'interfaccia della riga di comando di Azure per la prima volta. 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. A questo punto è necessario creare un secondo contenitore per i messaggi arricchiti.

Azure portal

1. Nella portale di Azure cercare gli account di archiviazione.

2. Selezionare l'account creato in precedenza.

3. Nel menu account di archiviazione selezionare Contenitori nella sezione Archiviazione dati .

4. Selezionare Contenitore per creare il nuovo contenitore.

   

5. Assegnare un nome al contenitore enrichede selezionare Crea.

Interfaccia della riga di comando di Azure

Suggerimento

Molti dei comandi dell'interfaccia della riga di comando usati in questa esercitazione usano gli stessi parametri. Per praticità, è possibile definire variabili locali che possono essere chiamate in base alle esigenze. Assicurarsi di eseguire tutti i comandi nella stessa sessione oppure è necessario ridefinire le variabili.

I valori per queste variabili devono essere per le 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 per la containerName variabile 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
   

Instradare i messaggi a un secondo endpoint

Creare un secondo endpoint e indirizzare i messaggi arricchiti.

Azure portal

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

2. Nel menu della risorsa in Impostazioni hub selezionare Routing messaggi e quindi Aggiungi.

   

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

   Parametro	Valore
   Tipo di endpoint	Selezionare Archiviazione.
   Nome endpoint	Immettere 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'AVRO predefinito.

   

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

5. Continuare a creare la nuova route, ora che è stato aggiunto l'endpoint di archiviazione. Specificare le informazioni seguenti per la nuova route:

   Parametro	Valore
   Nome	ContosoStorageRouteEnriched
   Origine dati	Verificare che i messaggi di telemetria del dispositivo siano selezionati dall'elenco a discesa.
   Abilitare la route	Verificare che questo campo sia impostato su enabled.
   Query di routing	immettere level="storage" come stringa di query.

   

6. Selezionare Crea + aggiungi arricchimenti.

Interfaccia della riga di comando di Azure

1. Configurare le variabili per i comandi endpoint e route per usare rispettivamente i valori ContosoStorageEndpointEnriched e ContosoStorageRouteEnriched.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

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

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

Aggiungere l'arricchimento dei messaggi al nuovo endpoint

Creare tre arricchimenti dei 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 che passano 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 essere simili a questa immagine:

   

2. Selezionare Aggiungi per aggiungere gli arricchimenti dei messaggi.

Interfaccia della riga di comando di Azure

Eseguire tre chiamate al comando az iot hub message-arricchimento create per aggiungere arricchimenti dei messaggi alla route che passa 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 disponibili arricchimenti dei messaggi configurati per tutti i messaggi indirizzati all'endpoint creato per i messaggi arricchiti. Se non si vuole aggiungere un tag di posizione al dispositivo gemello, è possibile passare alla sezione Arricchimenti messaggi di test 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 gemello, $twin.tags.locationverrà stampato come stringa per la chiave DeviceLocation negli arricchimenti dei messaggi.

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

Azure portal

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

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

3. Selezionare la scheda Dispositivo gemello nella parte superiore della pagina del dispositivo e aggiungere la riga seguente appena prima della parentesi graffe di chiusura nella parte inferiore del dispositivo gemello. Selezionare quindi 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 tag e valore.

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

Suggerimento

Attendere circa cinque minuti prima di continuare alla sezione successiva. Può richiedere fino a quel periodo per gli aggiornamenti al dispositivo gemello da riflettere nei valori di arricchimento dei messaggi.

Per altre informazioni sul modo in cui vengono gestiti i percorsi dei dispositivi gemelli con arricchimenti dei messaggi, vedere Limitazioni degli arricchimenti dei messaggi. Per altre informazioni sui dispositivi gemelli, vedere Comprendere e usare i dispositivi gemelli in hub IoT.

Testare gli arricchimenti dei messaggi

Dopo aver configurato gli arricchimenti dei messaggi 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.

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

Se non si esegue ancora l'applicazione console SimulatedDevice 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 /iot-hub/Tutorials/Routing/SimulatedDevice/ cartella.

2. Le definizioni delle variabili aggiornate prima devono comunque essere valide, ma, se non, modificarle nel Program.cs file:

   1. Trovare le definizioni delle variabili nella parte superiore della classe Program . 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 trovata nelle informazioni sull'identità del dispositivo.

   2. Salvare e chiudere il file.

3. Eseguire il codice di esempio:

   dotnet run
   

Dopo aver lasciato l'applicazione console da eseguire 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 nel corso di queste esercitazioni.

   

I messaggi nel contenitore denominati 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 arricchito fino a quando non si arriva alla fine e quindi aprire il file di messaggio più recente. Fare quindi lo stesso per l'altro contenitore per verificare che uno sia arricchito e non sia.

Quando si esaminano i messaggi arricchiti, si dovrebbe visualizzare "myIotHub" con il nome dell'hub, la posizione e l'ID cliente, come illustrato di seguito:

{
  "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 singole risorse all'interno per eliminare.

Azure portal

1. Nella portale di Azure passare al gruppo di risorse che contiene l'hub IoT e l'account di archiviazione per questa esercitazione.
2. Esaminare tutte le risorse presenti nel gruppo di risorse per determinare quali risorse si desidera pulire.
   • Se si vuole eliminare tutte le risorse, selezionare Elimina gruppo di risorse.
   • Se si vuole eliminare una determinata risorsa, usare le caselle di controllo accanto a ogni nome di risorsa per selezionare quelle che si desidera eliminare. Selezionare 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. Esaminare tutte le risorse presenti nel gruppo di risorse per determinare quali risorse si desidera 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 hub IoT messaggi quando vengono indirizzati a un endpoint.

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

Per altre informazioni su hub IoT, continuare con l'esercitazione successiva.

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