Esercitazione: Inviare dati del dispositivo ad Archiviazione di Azure usando hub IoT routing dei messaggi

Usare il routing dei messaggi in hub IoT di Azure per inviare dati di telemetria dai dispositivi IoT ai servizi di Azure, ad esempio l'archiviazione BLOB, le code del bus di servizio, gli argomenti del bus di servizio e gli hub eventi. Ogni hub IoT ha un endpoint predefinito compatibile con hub eventi. È anche possibile creare endpoint personalizzati e instradare messaggi ad altri servizi di Azure definendo le query di routing. Ogni messaggio che arriva all'hub IoT viene instradato a tutti gli endpoint i cui routing corrispondono alle query di routing. Se un messaggio non corrisponde a nessuna delle query di routing definite, viene instradato all'endpoint predefinito.

In questa esercitazione si eseguono le seguenti attività:

• Creare un hub IoT e inviarli messaggi di dispositivo.
• Creare un account di archiviazione.
• Creare un endpoint personalizzato per l'account di archiviazione e indirizzare i messaggi dall'hub IoT.
• Visualizzare i messaggi del dispositivo nel BLOB dell'account di archiviazione.

Prerequisiti

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

• Un hub IoT nella sottoscrizione di Azure. Se non si dispone ancora di un hub, è possibile seguire la procedura descritta in Creare un hub IoT.

• Questa esercitazione usa il codice di esempio di Azure IoT SDK per C#.

  • Scaricare o clonare il repository SDK nel computer di sviluppo.
  • Avere .NET Core 3.0.0 o versione successiva nel computer di sviluppo. Controllare la versione eseguendo dotnet --version e scaricare .NET se necessario.

• Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio 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).

• Facoltativamente, installare Azure IoT Explorer. Questo strumento consente di osservare i messaggi quando arrivano all'hub IoT. Questo articolo usa Azure IoT Explorer.

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.

Registrare un dispositivo e inviare messaggi a hub IoT

Registrare un nuovo dispositivo nell'hub IoT.

Azure portal

1. Accedere al portale di Azure e passare all'hub IoT.

2. Selezionare Dispositivi nella sezione Gestione dispositivi del menu.

3. Selezionare Aggiungi dispositivo.

   

4. Specificare un ID dispositivo e selezionare Salva.

5. Il nuovo dispositivo dovrebbe trovarsi nell'elenco dei dispositivi ora. In caso contrario, aggiornare la pagina. Selezionare l'ID dispositivo per aprire la pagina dei dettagli del dispositivo.

6. Copiare una delle chiavi del dispositivo e salvarla. Questo valore verrà usato per configurare il codice di esempio che genera messaggi di telemetria del dispositivo simulati.

   

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.

1. Definire le variabili per l'hub IoT e il dispositivo.

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

   DEVICE_NAME: sostituire questo segnaposto con qualsiasi nome da usare per il dispositivo in questa esercitazione.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Eseguire il comando az iot hub device-identity create nella shell dell'interfaccia della riga di comando. Questo comando crea l'identità del dispositivo.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. Dall'output dell'identità del dispositivo copiare il valore primaryKey senza virgolette circostanti e salvarlo. Questo valore verrà usato per configurare il codice di esempio che genera messaggi di telemetria del dispositivo simulati.

Ora che si dispone di un ID dispositivo e una chiave, usare il codice di esempio per avviare l'invio di messaggi di telemetria del dispositivo a hub IoT.

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. Se non si è fatto parte dei prerequisiti, scaricare o clonare il repository Azure IoT SDK per C# da GitHub.

2. Dalla cartella in cui è stato scaricato o clonato l'SDK azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample passare alla cartella.

3. Installare Azure IoT C# SDK e le dipendenze necessarie come specificato nel HubRoutingSample.csproj file:

   dotnet restore
   

4. In un editor scelto aprire il Parameters.cs file. Questo file mostra i parametri supportati dall'esempio. Solo il PrimaryConnectionString parametro verrà usato in questo articolo durante l'esecuzione dell'esempio. Esaminare il codice in questo file. Non sono necessarie modifiche.

5. Compilare ed eseguire il codice di esempio usando il comando seguente:

   Sostituire <myDevicePrimaryConnectionString> con la stringa di connessione primaria dal dispositivo nell'hub IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Si dovrebbe iniziare a visualizzare i messaggi stampati per l'output quando vengono inviati a hub IoT. Lasciare in esecuzione questo programma durante l'esercitazione.

Configurare IoT Explorer per visualizzare i messaggi

Configurare IoT Explorer per connettersi all'hub IoT e leggere i messaggi quando arrivano all'endpoint predefinito.

Recuperare prima di tutto la stringa di connessione per l'hub IoT.

Azure portal

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

2. Selezionare Criteri di accesso condiviso nella sezione Impostazioni di sicurezza del menu.

3. Selezionare il criterio iothubowner .

   

4. Copiare la stringa di connessione primaria.

   

Interfaccia della riga di comando di Azure

1. Eseguire il comando az iot hub connection-string show :

   az iot hub connection-string show --hub-name $hubName
   

2. Copiare la stringa di connessione senza le virgolette circostanti.

Usare ora tale stringa di connessione per configurare IoT Explorer per l'hub IoT.

1. Aprire IoT Explorer nel computer di sviluppo.

2. Selezionare Aggiungi connessione.

   

3. Incollare la stringa di connessione dell'hub nella casella di testo.

4. Selezionare Salva.

5. Dopo aver eseguito la connessione all'hub IoT, verrà visualizzato un elenco di dispositivi. Selezionare l'ID dispositivo creato per questa esercitazione.

6. Selezionare Telemetria.

7. Con il dispositivo ancora in esecuzione, selezionare Avvia. Se il dispositivo non è in esecuzione, i dati di telemetria non verranno visualizzati.

   

8. Dovrebbero essere visualizzati i messaggi in arrivo dal dispositivo, con il più recente visualizzato nella parte superiore.

   

   Esaminare i messaggi in arrivo per alcuni istanti per verificare che vengano visualizzati tre diversi tipi di messaggi: normale, di archiviazione e critico. Dopo aver visualizzato questo problema, è possibile arrestare il dispositivo.

Questi messaggi arrivano tutti all'endpoint predefinito predefinito per l'hub IoT. Nelle sezioni successive si creerà un endpoint personalizzato e si instradano alcuni di questi messaggi all'archiviazione in base alle proprietà del messaggio. Questi messaggi smetteranno di essere visualizzati in IoT Explorer perché i messaggi passano solo all'endpoint predefinito quando non corrispondono ad altre route nell'hub IoT.

Configurazione del routing dei messaggi

Si instradano i messaggi a risorse diverse in base alle proprietà associate al messaggio dal dispositivo simulato. I messaggi non indirizzati personalizzati vengono inviati all'endpoint predefinito (messaggi/eventi).

L'app di esempio per questa esercitazione assegna una proprietà di livello a ogni messaggio inviato all'hub IoT. A ogni messaggio viene assegnato in modo casuale un livello normale,di archiviazione o critico.

Il primo passaggio consiste nell'impostare l'endpoint a cui verranno instradati i dati. Il secondo passaggio consiste nel configurare la route di messaggi che usa tale endpoint. Dopo aver configurato il routing, è possibile visualizzare gli endpoint e le route dei messaggi nel portale.

Creare un account di archiviazione

Creare un account di archiviazione di Azure e un contenitore all'interno di tale account, che conterrà i messaggi del dispositivo indirizzati.

Azure portal

1. Nella portale di Azure cercare Account di archiviazione.

2. Selezionare Crea.

3. Specificare i valori seguenti per l'account di archiviazione:

   Parametro	Valore
   Sottoscrizione	Selezionare la stessa sottoscrizione che contiene l'hub IoT.
   Gruppo di risorse	Selezionare lo stesso gruppo di risorse che contiene l'hub IoT.
   Nome account di archiviazione	Specificare un nome univoco globale per l'account di archiviazione.
   Prestazioni	Accettare il valore Standard predefinito.

   

4. È possibile accettare tutti gli altri valori predefiniti selezionando Rivedi e crea.

5. Al termine della convalida selezionare Crea.

6. Al termine della distribuzione selezionare Vai alla risorsa.

7. Nel menu dell'account di archiviazione selezionare Contenitori nella sezione Archiviazione dati .

8. Selezionare + Contenitore per creare un nuovo contenitore.

   

9. Specificare un nome per il contenitore e selezionare Crea.

Interfaccia della riga di comando di Azure

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

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

   STORAGE_NAME: sostituire questo segnaposto con un nome per l'account di archiviazione. I nomi degli account di archiviazione devono essere minuscoli e univoci a livello globale.

   CONTAINER_NAME: sostituire questo segnaposto con un nome per il contenitore.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Usare il comando az storage account create per creare un account di archiviazione standard per utilizzo generico v2.

   az storage account create --name $storageName --resource-group $resourceGroup
   

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

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

Creare la route a un account di archiviazione

Ora configurare il routing per l'account di archiviazione. In questa sezione viene definito un nuovo endpoint che punta all'account di archiviazione creato. Creare quindi una route che filtra i messaggi in cui la proprietà level è impostata sull'archiviazione e instradarli all'endpoint di archiviazione.

Nota

I dati possono essere scritti nell'archivio BLOB nel formato Apache Avro , ovvero l'impostazione predefinita o JSON.

Il formato di codifica può essere impostato solo al momento della configurazione dell'endpoint di archiviazione BLOB. Non è possibile modificare il formato di un endpoint già configurato. Quando si usa la codifica JSON è necessario impostare contentType su JSON e contentEncoding su UTF-8 nelle proprietà di sistema del messaggio.

Per informazioni più dettagliate sull'uso di un endpoint di archiviazione BLOB, vedere le indicazioni sul routing all'archiviazione.

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 specificando le informazioni seguenti:

   Parametro	Valore
   Tipo di endpoint	Selezionare Archiviazione.
   Nome endpoint	Specificare un nome univoco per questo endpoint.
   Contenitore di Archiviazione di Azure	Scegliere Selezionare un contenitore. Seguire le istruzioni per selezionare l'account di archiviazione e il contenitore creati 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. Nella scheda Route specificare le informazioni seguenti per creare una route che punti all'endpoint di archiviazione creato:

   Parametro	Valore
   Nome	Creare un nome per la route.
   Origine dati	Verificare che i messaggi di telemetria dispositivo siano selezionati nell'elenco a discesa.
   Abilitare la route	Verificare che il campo sia selezionato.
   Query di routing	immettere level="storage" come stringa di query.

   

6. Selezionare Crea + ignora arricchimenti.

Interfaccia della riga di comando di Azure

1. Configurare le variabili necessarie per i comandi endpoint e route.

   ENDPOINT_NAME: specificare un nome per l'endpoint che rappresenta il contenitore di archiviazione.

   ROUTE_NAME: specificare un nome per la route che filtra i messaggi per l'endpoint di archiviazione

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

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

Visualizzare i messaggi indirizzati

Dopo aver creato la route in hub IoT e abilitata, verrà immediatamente avviato il routing dei messaggi che soddisfano la condizione di query all'endpoint di archiviazione.

Monitorare l'endpoint predefinito con IoT Explorer

Tornare alla sessione di IoT Explorer nel computer di sviluppo. Si noti che IoT Explorer monitora l'endpoint predefinito per l'hub IoT. Ciò significa che ora è necessario visualizzare solo i messaggi che non vengono indirizzati dalla route personalizzata creata.

Avviare di nuovo l'esempio eseguendo il codice. Guarda i messaggi in arrivo per alcuni momenti e dovresti visualizzare solo i messaggi in cui level è impostato su normal o critical.

Visualizzare i messaggi nel contenitore di archiviazione

Verificare che i messaggi vengano ricevuti nel contenitore di archiviazione.

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

2. Selezionare Contenitori nella sezione Archiviazione dati del menu.

3. Selezionare il contenitore creato per questa esercitazione.

4. Deve essere presente una cartella con il nome dell'hub IoT. Eseguire il drill-down della struttura di file fino a quando non si ottiene un file json .

   

5. Selezionare il file JSON e quindi scaricare il file JSON. Verificare che il file contenga messaggi dal dispositivo con la level proprietà impostata su storage.

6. Arrestare l'esecuzione dell'esempio.

Pulire le risorse

Per rimuovere tutte le risorse di Azure usate per 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, usare il portale di Azure per individuare ed eliminare le singole risorse.

Se si intende continuare all'esercitazione successiva, mantenere le risorse create qui.

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 si è appreso come creare un endpoint personalizzato per una risorsa di Azure e quindi creare una route per inviare messaggi di dispositivo a tale endpoint. Continuare con l'esercitazione successiva per informazioni su come arricchire i messaggi con dati aggiuntivi che possono essere usati per semplificare l'elaborazione downstream

Usare hub IoT di Azure arricchimenti dei messaggi