Esercitazione: Inviare dati del dispositivo ad Archiviazione di Azure usando il routing dei messaggi dell'hub IoT
Usare il routing dei messaggi nell'hub IoT di Azure per inviare dati di telemetria dai dispositivi IoT ai servizi di Azure, ad esempio archiviazione BLOB, code del bus di servizio, argomenti del bus di servizio e hub eventi. Ogni hub IoT include un endpoint predefinito compatibile con hub eventi. È anche possibile creare endpoint personalizzati e indirizzare i messaggi ad altri servizi di Azure definendo query di routing. Ogni messaggio che arriva all'hub IoT viene instradato a tutti gli endpoint di cui corrisponde il routing delle query. Se un messaggio non corrisponde ad alcuna delle query di routing definita, viene indirizzato all'endpoint predefinito.
In questa esercitazione si eseguono le seguenti attività:
- Creare un hub IoT e inviargli i messaggi del dispositivo.
- Creare un account di archiviazione.
- Creare un endpoint personalizzato per l'account di archiviazione e instradarvi i messaggi dall'hub IoT.
- Visualizzare i messaggi del dispositivo nel BLOB dell'account di archiviazione.
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 ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.
Questa esercitazione usa il codice di esempio dell'SDK di Azure IoT per C#.
- Scaricare o clonare il repository SDK da GitHub nel computer di sviluppo.
- È necessario .NET Core SDK 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. In questo articolo viene usato Azure IoT Explorer.
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.
Registrare un nuovo dispositivo nell'hub IoT.
Importante
Questo articolo include la procedura per connettere un dispositivo usando una firma di accesso condiviso, altrimenti chiamata autenticazione con chiave simmetrica. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione tramite certificati X.509 rappresenta un approccio più sicuro. Per scoprire di più, vedere Procedure consigliate per la sicurezza >Sicurezza della connessione.
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.
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 un nome da usare per il dispositivo in questa esercitazione.
hubName=IOTHUB_NAME deviceName=DEVICE_NAME
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
Dall'output device-identity copiare il valore primaryKey senza le virgolette circostanti e salvarlo. Questo valore verrà usato per configurare il codice di esempio che genera messaggi di telemetria del dispositivo simulato.
Si noti che esiste un ID dispositivo e una chiave. Usare il codice di esempio per avviare l'invio dei messaggi di telemetria del dispositivo all'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.
Se l'operazione non è stata eseguita come parte dei prerequisiti, scaricare o clonare l'SDK di Azure IoT per il repository C# da GitHub.
Dalla cartella in cui è stato scaricato o clonato l'SDK, passare alla cartella
azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample
.Installare l'SDK di Azure IoT per C# e le dipendenze necessarie come specificato nel file
HubRoutingSample.csproj
:dotnet restore
In un editor a scelta, aprire il file
Parameters.cs
. Questo file mostra i parametri supportati dall'esempio. In questo articolo verrà usato solo il parametroPrimaryConnectionString
durante l'esecuzione dell'esempio. Rivedere il codice di questo file: Non sono necessarie modifiche.Compilare ed eseguire il codice di esempio usando il comando seguente:
Sostituire
<myDevicePrimaryConnectionString>
con la stringa di connessione primaria del dispositivo all'hub IoT.dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
Si comincia a visualizzare i messaggi stampati nell'output mano a mano che vengono inviati all'hub IoT. Lasciare il programma in esecuzione durante l'esercitazione.
Configurare IoT Explorer per connettersi all'hub IoT e leggere i messaggi mano a mano che arrivano all'endpoint predefinito.
Innanzitutto, recuperare la stringa di connessione per l'hub IoT.
Eseguire il comando az iot hub connection-string show:
az iot hub connection-string show --hub-name $hubName
Copiare la stringa di connessione senza le virgolette circostanti.
A questo punto, usare tale stringa di connessione per configurare IoT Explorer per l'hub IoT.
Aprire IoT Explorer nel computer di sviluppo.
Selezionare Aggiungi connessione.
Incollare la stringa di connessione dell'hib nella casella di testo.
Seleziona Salva.
Una volta connessi all'hub IoT, verrà visualizzato un elenco di dispositivi. Selezionare l'ID dispositivo creato per questa esercitazione.
Seleziona Telemetria.
Con il dispositivo ancora in esecuzione, selezionare Avvia. Se il dispositivo non è in esecuzione, non verranno visualizzati i dati di telemetria.
Vengono visualizzati i messaggi in arrivo dal dispositivo, con il più recente visualizzato in cima.
Osservare i messaggi in arrivo per alcuni istanti per assicurarsi che vengano visualizzati tre tipi diversi di messaggi: normale, archiviazione e critico. Una volta visualizzati, è possibile arrestare il dispositivo.
Questi messaggi arrivano tutti all'endpoint predefinito per l'hub IoT. Nelle sezioni successive si creerà un endpoint personalizzato e si instraderanno alcuni di questi messaggi alla risorsa di archiviazione in base alle proprietà dei messaggi. Questi messaggi smetteranno di apparire in IoT Explorer perché i messaggi passano all'endpoint predefinito solo quando non corrispondono ad altre route nell'hub IoT.
I messaggi verranno instradati a diverse risorse in base alle proprietà allegate al messaggio dal dispositivo simulato. I messaggi che non sono instradati in modo personalizzato vengono inviati all'endpoint predefinito (messaggi/eventi).
L'app di esempio per questa esercitazione assegna una proprietà livello a ogni messaggio che invia all'hub IoT. A ogni messaggio viene assegnato in modo casuale un livello normale, 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 di messaggi nel portale.
Creare un account di archiviazione di Azure e un contenitore all'interno di tale account, che conterrà i messaggi del dispositivo indirizzati.
Definire le variabili per il contenitore e l'account di archiviazione.
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 contenere solo caratteri minuscoli e devono essere univoci a livello globale.
CONTAINER_NAME: sostituire questo segnaposto con un nome per il contenitore.
resourceGroup=GROUP_NAME storageName=STORAGE_NAME containerName=CONTAINER_NAME
Usare il comando az storage account create per creare un account di archiviazione v2 per scopi generali standard.
az storage account create --name $storageName --resource-group $resourceGroup
Usare az storage container create per aggiungere un contenitore all'account di archiviazione.
az storage container create --auth-mode login --account-name $storageName --name $containerName
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à livello è impostata su archiviazione e instradarli all'endpoint di archiviazione.
Nota
I dati possono essere scritti nell'archiviazione BLOB in formato Apache Avro, che è quello predefinito, o in formato 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.
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 scoprire di più, vedere Procedure consigliate per la sicurezza >Sicurezza cloud.
Configurare le variabili necessarie per l'endpoint e i comandi di 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
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 storage-container \ --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
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"'
Dopo aver creato e abilitato la route nell'hub IoT, si avvierà immediatamente il routing dei messaggi che soddisfano la condizione di query all'endpoint di archiviazione.
Tornare alla sessione di IoT Explorer nel computer di sviluppo. Tenere presente che IoT Explorer monitora l'endpoint predefinito per l'hub IoT. Ciò implica che ora vengono visualizzati solo i messaggi non instradati dalla route personalizzata creata.
Avviare nuovamente l'esempio eseguendo il codice. Osservare i messaggi in arrivo per alcuni istanti e visualizzare solo i messaggi in cui level
è impostato su normal
o critical
.
Assicurarsi che i messaggi arrivino nel contenitore di archiviazione.
Nel portale di Azure passare all'account di archiviazione.
Nella sezione Archiviazione dati del menu, selezionare Contenitori.
Selezionare il contenitore creato per questa esercitazione.
È presente una cartella con il nome dell'hub IoT. Eseguire il drill-down della struttura di file finché non si arriva a un file .json.
Selezionare il file JSON, quindi selezionare Scarica per scaricare il file JSON. Assicurarsi che il file contenga i messaggi provenienti dal dispositivo con la proprietà
level
impostata sustorage
.Arrestare l'esecuzione dell'esempio.
Se si desiderano 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 desidera eliminare l'intero gruppo di risorse, usare il portale di Azure per individuare ed eliminare le singole risorse.
Se si intende di continuare con l'esercitazione successiva, non eliminare le risorse create in questa esercitazione.
Usare il comando az resource list per visualizzare tutte le risorse nel gruppo di risorse.
az resource list --resource-group $resourceGroup --output table
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
In questa esercitazione si è appreso come creare un endpoint personalizzato per una risorsa di Azure e quindi creare una route per inviare messaggi del 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