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

Usare il routing dei messaggi in hub IoT di Azure per inviare dati di telemetria dai dispositivi IoT ai servizi di Azure, ad esempio archiviazione BLOB, code bus di servizio, argomenti bus di servizio e Hub eventi. Ogni hub IoT ha un endpoint predefinito compatibile con Hub eventi. È anche possibile creare endpoint personalizzati e indirizzare i messaggi ad altri servizi di Azure definendo le 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 inviarli 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.

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 ha ancora 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 tramite l'interfaccia della riga di comando di Azure.

  • Quando richiesto, installare l'estensione dell'interfaccia della riga di comando di Azure al primo utilizzo. 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 dalla sezione Gestione dei dispositivi del menu.

3. Selezionare Aggiungi dispositivo.

   

4. Specificare un ID dispositivo e selezionare Salva.

5. Il nuovo dispositivo dovrebbe essere ora incluso nell'elenco dei dispositivi. 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 simulato.

   

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à, sono disponibili 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 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.

Ora che si dispone di un ID dispositivo e una chiave, usare il codice di esempio per iniziare a inviare 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 ora.

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

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

   dotnet restore
   

4. In un editor di propria scelta 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 il stringa di connessione primario dal dispositivo nell'hub IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. È consigliabile iniziare a visualizzare i messaggi stampati nell'output man mano che vengono inviati a hub IoT. Lasciare il programma in esecuzione 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 il 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 il stringa di connessione primario.

   

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 il stringa di connessione senza le virgolette circostanti.

Usare ora questa 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 il stringa di connessione dell'hub nella casella di testo.

4. Seleziona 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. Seleziona Telemetria.

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

   

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

   

   Osservare i messaggi in arrivo per alcuni istanti per verificare che vengano visualizzati tre tipi diversi di messaggi: normale, 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 apparire in IoT Explorer perché i messaggi passano all'endpoint predefinito solo 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 di 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 dei messaggi nel portale.

Creare un account di archiviazione

Creare un account 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 gli account Archiviazione.

2. Seleziona Crea.

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

   Parametro	Valore
   Abbonamento	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. Archiviazione nomi di account 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 delle risorse in Impostazioni hub selezionare Routing messaggi e quindi Aggiungi.

   

3. Nella scheda Endpoint creare un endpoint Archiviazione specificando le informazioni seguenti:

   Parametro	Valore
   Tipo di endpoint	Selezionare Archiviazione.
   Nome endpoint	Specificare un nome univoco per questo endpoint.
   contenitore 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 Archiviazione creato:

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

   

6. Selezionare Crea e ignora arricchimenti.

Interfaccia della riga di comando di Azure

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

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

3. Usare il comando az iot hub message-route create per creare una route che passa qualsiasi messaggio in cui level=storage si trova 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"'
   

Visualizzare i messaggi indirizzati

Una volta creata la route in hub IoT e abilitata, avvierà immediatamente 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. Tenere presente che IoT Explorer monitora l'endpoint predefinito per l'hub IoT. Ciò significa che ora si dovrebbero 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 istanti 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 arrivino 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. Dovrebbe essere presente una cartella con il nome dell'hub IoT. Eseguire il drill-down della struttura di file fino a quando non si arriva a un file .json .

   

5. Selezionare il file JSON, quindi selezionare Scarica per 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 con l'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.
   • Per eliminare tutte le risorse, selezionare Elimina gruppo di risorse.
   • Se si vuole eliminare solo una determinata risorsa, usare le caselle di controllo accanto a ogni nome di 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. Esaminare tutte le risorse presenti nel gruppo di risorse per determinare quali risorse si desidera pulire.

   • Per eliminare tutte le risorse, usare il comando az group delete .

     az group delete --name $resourceGroup
     

   • Se si vogliono 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 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

Usare gli arricchimenti di messaggi hub IoT di Azure