Introduzione ai dispositivi gemelli (interfaccia della riga di comando di Azure)

• CLI
• .NET
• Python
• Node.JS
• Java

i dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT basic e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.

Usare i dispositivi gemelli per:

• Archiviare i metadati dei dispositivi dal back-end della soluzione.

• Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi.

• Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata (come gli aggiornamenti del firmware e della configurazione) tra un'app per dispositivi e un'app di back-end.

• Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Per altre informazioni sui dispositivi gemelli, tra cui quando usare dispositivi gemelli, vedere Informazioni sui dispositivi gemelli.

Gli hub IoT archiviano i dispositivi gemelli, che contengono gli elementi seguenti:

• Tag. Metadati dei dispositivi accessibili solo dal back-end della soluzione.

• Proprietà desiderate. Oggetti JSON modificabili dal back-end della soluzione e osservabili dall'app per dispositivi.

• Proprietà segnalate. Oggetti JSON modificabili dall'app per dispositivi e leggibili dal back-end della soluzione.

I tag e le proprietà non possono contenere matrici, ma possono contenere oggetti annidati.

Nella figura seguente viene illustrata l'organizzazione di un dispositivo gemello:

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Per altre informazioni sui dispositivi gemelli, vedere Informazioni sui dispositivi gemelli. Per altre informazioni sulle query, vedere Linguaggio di query di hub IoT.

Questo articolo illustra come:

• Usare un dispositivo simulato per segnalare il canale di connettività come proprietà segnalata nel dispositivo gemello.

• Eseguire query sui dispositivi usando filtri per i tag e le proprietà creati in precedenza.

Per altre informazioni sull'uso delle proprietà segnalate del dispositivo gemello, vedere Linee guida per la comunicazione da dispositivo a cloud.

Questo articolo illustra come creare due sessioni dell'interfaccia della riga di comando di Azure:

• Sessione che crea un dispositivo simulato. Il dispositivo simulato segnala il canale di connettività come proprietà segnalata nel dispositivo gemello corrispondente del dispositivo quando viene inizializzato.

• Sessione che aggiorna i tag del dispositivo gemello per il dispositivo simulato, quindi esegue query sui dispositivi dall'hub IoT. Le query usano filtri in base ai tag e alle proprietà aggiornati in precedenza in entrambe le sessioni.

Prerequisiti

• Interfaccia della riga di comando di Azure. È anche possibile eseguire i comandi in questo articolo usando Azure Cloud Shell, una shell interattiva dell'interfaccia della riga di comando eseguita nel browser o in un'app come Terminale Windows. Se si usa Cloud Shell, non è necessario installare alcun componente. Se si preferisce usare l'interfaccia della riga di comando in locale, questo articolo richiede l'interfaccia della riga di comando di Azure versione 2.36 o successiva. Eseguire az --version per trovare la versione. Per installare o aggiornare localmente l'interfaccia della riga di comando di Azure, vedere Installare l'interfaccia della riga di comando di Azure.

• Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.

• Assicurarsi che la porta 8883 sia aperta nel firewall. Gli esempi in questo articolo usano il protocollo MQTT, che comunica sulla porta 8883. Questa porta può 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).

Preparare Cloud Shell

Se si vuole usare Azure Cloud Shell, è prima necessario avviarlo e configurarlo. Se si usa l'interfaccia della riga di comando in locale, passare alla sezione Preparare due sessioni dell'interfaccia della riga di comando.

1. Selezionare l'icona di Cloud Shell nell'intestazione della pagina nella portale di Azure.

   

   Nota

   Se è la prima volta che si usa Cloud Shell, viene richiesto di creare una risorsa di archiviazione necessaria per usare Cloud Shell. Selezionare una sottoscrizione per creare un account di archiviazione e una condivisione File di Microsoft Azure.

2. Usare il selettore di ambiente nella barra degli strumenti di Cloud Shell per selezionare l'ambiente dell'interfaccia della riga di comando preferito. Questo articolo usa l'ambiente Bash . È anche possibile usare l'ambiente PowerShell .

   Nota

   Alcuni comandi richiedono sintassi o formattazione diversi negli ambienti Bash e PowerShell . Per altre informazioni, vedere Suggerimenti per l'uso dell'interfaccia della riga di comando di Azure.

   

Preparare due sessioni dell'interfaccia della riga di comando

Successivamente, è necessario preparare due sessioni dell'interfaccia della riga di comando di Azure. Se si usa Cloud Shell, eseguire queste sessioni in schede di Cloud Shell separate. Se si usa un client dell'interfaccia della riga di comando locale, eseguire istanze separate dell'interfaccia della riga di comando. Usare le sessioni separate dell'interfaccia della riga di comando per le attività seguenti:

• La prima sessione simula un dispositivo IoT che comunica con l'hub IoT.
• La seconda sessione aggiorna il dispositivo simulato ed esegue query sull'hub IoT.

1. Se si usa Cloud Shell, passare al passaggio successivo. In caso contrario, eseguire il comando az login nella prima sessione dell'interfaccia della riga di comando per accedere all'account Azure.

   Se si usa Cloud Shell, si accede automaticamente all'account Azure. Tutte le comunicazioni tra la sessione dell'interfaccia della riga di comando di Azure e l'hub IoT vengono autenticate e crittografate. Di conseguenza, questo articolo non richiede l'autenticazione aggiuntiva usata con un dispositivo reale, ad esempio un stringa di connessione. Per altre informazioni sull'accesso con l'interfaccia della riga di comando di Azure, vedere Accedere con l'interfaccia della riga di comando di Azure.

   az login
   

2. Nella prima sessione dell'interfaccia della riga di comando eseguire il comando az extension add . Il comando aggiunge l'estensione Microsoft Azure IoT per l'interfaccia della riga di comando di Azure alla shell dell'interfaccia della riga di comando. L'estensione aggiunge hub IoT, IoT Edge e i comandi specifici del servizio Device Provisioning IoT all'interfaccia della riga di comando di Azure. Dopo aver installato l'estensione, non è necessario installarla di nuovo in alcuna sessione di Cloud Shell.

   az extension add --name azure-iot
   

   Nota

   Questo articolo usa la versione più recente dell'estensione Azure IoT, denominata azure-iot. La versione legacy viene chiamata azure-cli-iot-ext. Deve essere installata solo una versione alla volta. È possibile usare il comando az extension list per convalidare le estensioni attualmente installate.

   Usare az extension remove --name azure-cli-iot-ext per rimuovere la versione legacy dell'estensione.

   Usare az extension add --name azure-iot per aggiungere la nuova versione dell'estensione.

   Per visualizzare le estensioni installate, usare az extension list.

3. Aprire la seconda sessione dell'interfaccia della riga di comando. Se si usa Cloud Shell in un browser, selezionare l'icona Apri nuova sessione sulla barra degli strumenti della prima sessione dell'interfaccia della riga di comando. Se si usa l'interfaccia della riga di comando in locale, aprire una seconda istanza dell'interfaccia della riga di comando.

   

Creare e simulare un dispositivo

In questa sezione viene creata un'identità del dispositivo per l'hub IoT nella prima sessione dell'interfaccia della riga di comando e quindi si simula un dispositivo usando tale identità del dispositivo. Il dispositivo simulato risponde ai processi pianificati nella seconda sessione dell'interfaccia della riga di comando.

Per creare e avviare un dispositivo simulato:

1. Nella prima sessione dell'interfaccia della riga di comando eseguire il comando az iot hub device-identity create , sostituendo i segnaposto seguenti con i valori corrispondenti. Questo comando crea l'identità del dispositivo per il dispositivo simulato.

   {DeviceName}. Nome del dispositivo simulato.

   {HubName}. Il nome dell'hub IoT.

   az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
   

2. Nella prima sessione dell'interfaccia della riga di comando eseguire il comando az iot device simulate , sostituendo i segnaposto seguenti con i valori corrispondenti. Questo comando simula il dispositivo creato nel passaggio precedente. Il comando configura anche il dispositivo simulato per segnalare il canale di connettività come proprietà segnalata nel dispositivo gemello corrispondente del dispositivo quando viene inizializzato.

   {DeviceName}. Nome del dispositivo simulato.

   {HubName}. Il nome dell'hub IoT.

   az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                          --init-reported-properties '{"connectivity":{"type": "cellular"}}'
   

   Suggerimento

   Per impostazione predefinita, il comando az iot device simulate invia 100 messaggi da dispositivo a cloud con un intervallo di 3 secondi tra i messaggi. La simulazione termina dopo l'invio di tutti i messaggi. Se si vuole che la simulazione venga eseguita più a lungo, è possibile usare il --msg-count parametro per specificare più messaggi o il --msg-interval parametro per specificare un intervallo più lungo tra i messaggi. È anche possibile eseguire di nuovo il comando per riavviare il dispositivo simulato.

Aggiornare il dispositivo gemello

Dopo aver creato un'identità del dispositivo, un dispositivo gemello viene creato in modo implicito in hub IoT. In questa sezione si usa la seconda sessione dell'interfaccia della riga di comando per aggiornare un set di tag nel dispositivo gemello associato all'identità del dispositivo creata nella sezione precedente. È possibile usare i tag dei dispositivi gemelli per organizzare e gestire i dispositivi nelle soluzioni IoT. Per altre informazioni sulla gestione dei dispositivi tramite tag, vedere Come gestire i dispositivi usando i tag dei dispositivi gemelli in hub IoT di Azure.

1. Verificare che il dispositivo simulato nella prima sessione dell'interfaccia della riga di comando sia in esecuzione. In caso contrario, riavviarlo eseguendo di nuovo il comando az iot device simulate da Crea e simulare un dispositivo.

2. Nella seconda sessione dell'interfaccia della riga di comando eseguire il comando az iot hub device-twin update , sostituendo i segnaposto seguenti con i valori corrispondenti. In questo esempio vengono aggiornati più tag nel dispositivo gemello per l'identità del dispositivo creata nella sezione precedente.

   {DeviceName}. Nome del dispositivo.

   {HubName}. Il nome dell'hub IoT.

   az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                                 --tags '{"location":{"region":"US","plant":"Redmond43"}}'
   

3. Nella seconda sessione dell'interfaccia della riga di comando verificare che la risposta JSON mostri i risultati dell'operazione di aggiornamento. Nell'esempio di risposta JSON seguente è stato usato SampleDevice per il {DeviceName} segnaposto nel comando dell'interfaccia della az iot hub device-twin update riga di comando.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

Eseguire query nell'hub IoT per i dispositivi gemelli

hub IoT espone i dispositivi gemelli per l'hub IoT come raccolta di documenti denominata dispositivi. In questa sezione viene usata la seconda sessione dell'interfaccia della riga di comando per eseguire due query sul set di dispositivi gemelli per l'hub IoT: la prima query seleziona solo i dispositivi gemelli dei dispositivi che si trovano nell'impianto Redmond43 e la seconda affina la query per selezionare solo i dispositivi connessi tramite una rete cellulare. Entrambe le query restituiscono solo i primi 100 dispositivi nel set di risultati. Per altre informazioni sulle query dei dispositivi gemelli, vedere Query per hub IoT dispositivo e moduli gemelli.

1. Verificare che il dispositivo simulato nella prima sessione dell'interfaccia della riga di comando sia in esecuzione. In caso contrario, riavviarlo eseguendo di nuovo il comando az iot device simulate da Crea e simulare un dispositivo.

2. Nella seconda sessione dell'interfaccia della riga di comando eseguire il comando az iot hub query , sostituendo i segnaposto seguenti con i valori corrispondenti. In questo esempio viene filtrata la query per restituire solo i dispositivi gemelli dei dispositivi che si trovano nell'impianto Redmond43 .

   {HubName}. Il nome dell'hub IoT.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                    --top 100
   

3. Nella seconda sessione dell'interfaccia della riga di comando verificare che la risposta JSON mostri i risultati della query.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

4. Nella seconda sessione dell'interfaccia della riga di comando eseguire il comando az iot hub query , sostituendo i segnaposto seguenti con i valori corrispondenti. In questo esempio viene filtrata la query per restituire solo i dispositivi gemelli dei dispositivi che si trovano nell'impianto Redmond43 connessi anche tramite una rete cellulare.

   {HubName}. Il nome dell'hub IoT.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                     AND properties.reported.connectivity.type = 'cellular'" \
                    --top 100
   

5. Nella seconda sessione dell'interfaccia della riga di comando verificare che la risposta JSON mostri i risultati della query. I risultati di questa query devono corrispondere ai risultati della query precedente in questa sezione.

In questo articolo si apprenderà come:

• Aggiunta dei metadati del dispositivo come tag da una sessione dell'interfaccia della riga di comando di Azure
• Simulato un dispositivo che ha segnalato le informazioni di connettività del dispositivo nel dispositivo gemello
• Query sulle informazioni sul dispositivo gemello usando un linguaggio di query simile a SQL hub IoT in una sessione dell'interfaccia della riga di comando di Azure

Passaggi successivi

Per scoprire come:

• Inviare dati di telemetria dai dispositivi, vedere Avvio rapido: Inviare dati di telemetria da un dispositivo Plug and Play IoT a hub IoT di Azure.

• Configurare i dispositivi usando le proprietà desiderate del dispositivo gemello, vedere Esercitazione: Configurare i dispositivi da un servizio back-end.

• Controllare i dispositivi in modo interattivo, ad esempio accendere una ventola da un'app controllata dall'utente, vedere Avvio rapido: Controllare un dispositivo connesso a un hub IoT.