Introduzione ai dispositivi gemelli (.NET/.NET)

I dispositivi gemelli sono documenti JSON nei quali vengono archiviate informazioni sullo stato dei dispositivi (metadati, configurazioni e condizioni). L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

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

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Altre informazioni su quando usare i dispositivi gemelli sono reperibili in Informazioni sui dispositivi gemelli.

I dispositivi gemelli vengono archiviati in un hub IoT e 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 gli oggetti possono essere annidati.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Vedere Informazioni sui dispositivi gemelli per altre informazioni sui dispositivi gemelli e Linguaggio di query per hub IoT per informazioni sull'esecuzione di query.

Questa esercitazione illustra come:

  • Creare un'app back-end che aggiunge tag a un dispositivo gemello e un'app per dispositivo simulato che segnala il proprio canale di connettività come proprietà segnalata nel dispositivo gemello.
  • Eseguire query sui dispositivi dall'app back-end con filtri sui tag e sulle proprietà creati in precedenza.

Al termine di questa esercitazione si avranno queste due app console .NET:

  • CreateDeviceIdentity, un'app .NET che crea un'identità del dispositivo e la chiave di sicurezza associata per connettere l'app per dispositivo simulato.
  • AddTagsAndQuery, un'app back-end .NET, che aggiunge tag ed effettua una query dei dispositivi gemelli.
  • ReportConnectivity.js, un dispositivo .NET che simula un dispositivo che si connette all'hub IoT con l'identità del dispositivo creata prima e segnala la condizione della connettività.
Nota

L'articolo Azure IoT SDK contiene informazioni sui componenti Azure IoT SDK che consentono di compilare le app back-end e per dispositivi.

Per completare l'esercitazione, sono necessari gli elementi seguenti:

  • Visual Studio 2015 o Visual Studio 2017.
  • Un account Azure attivo. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.

Creare un hub IoT

Creare un hub IoT per connettere l'app per dispositivo simulato. La procedura seguente illustra come completare questa attività usando il portale di Azure.

  1. Accedere al portale di Azure.
  2. Nell'indice fare clic su Nuovo > Internet delle cose > Hub IoT.

    Indice del portale di Azure

  3. Nella finestra Hub IoT scegliere la configurazione per l'hub IoT.

    Finestra Hub IoT

    1. Nella casella Nome immettere un nome per l'hub IoT. Se il Nome è valido e disponibile, appare un segno di spunta verde nella casella Nome.

      Importante

      L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

    2. Selezionare un piano tariffario e un livello di scalabilità. Per questa esercitazione non è necessario un livello specifico. Per questa esercitazione, usare il livello F1 gratuito.

    3. In Gruppo di risorse creare un gruppo di risorse o selezionarne uno esistente. Per altre informazioni, vedere Using resource groups to manage your Azure resources (Uso di Gruppi di risorse per gestire le risorse di Azure).
    4. In Percorsoselezionare il percorso per ospitare l'hub IoT. Per questa esercitazione, scegliere la località più vicina.
  4. Dopo aver scelto le opzioni di configurazione dell'hub IoT, fare clic su Crea. La creazione dell'hub IoT da parte di Azure può richiedere alcuni minuti. Per verificare lo stato, è possibile monitorare l'avanzamento nella Schermata iniziale o nel pannello Notifiche.

  5. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro dell'hub IoT nel portale di Azure per aprire la finestra delle proprietà. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.

    Finestra del nuovo hub IoT

  6. In Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nella finestra iothubowner. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".

    Criteri di accesso condivisi

Creare un'identità del dispositivo

In questa sezione si usa il portale di Azure per creare un'identità del dispositivo nel registro delle identità dell'hub IoT. Un dispositivo non può connettersi all'hub IoT a meno che non abbia una voce nel registro di identità. Per altre informazioni, vedere la sezione "Registro di identità" della Guida per gli sviluppatori dell'hub IoT. Nel portale, Device Explorer consente di generare una chiave e un ID dispositivo univoci con cui il dispositivo può identificarsi quando si connette all'hub IoT. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.

  1. Assicurarsi di aver eseguito l'accesso al portale di Azure.

  2. Nell'indice fare clic su Tutte le risorse e trovare la risorsa hub IoT.

    Passare all'hub IoT

  3. Dopo aver aperto la risorsa hub IoT, fare clic sullo strumento Device Explorer e quindi su Aggiungi nella parte superiore. Specificare un nome per il nuovo dispositivo, ad esempio myDeviceId e fare clic su Salva.

    Creare l'identità del dispositivo nel portale

    In questo modo viene creata una nuova identità del dispositivo per l'hub IoT.

    Importante

    L'ID dispositivo può essere visibile nei log raccolti per il supporto tecnico e la risoluzione dei problemi, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

  4. Nell'elenco dei dispositivi in Device Explorer fare clic sul dispositivo appena creato e prendere nota della Stringa di connessione - chiave primaria.

    Stringa di connessione del dispositivo

Nota

Il registro di identità dell'hub IoT archivia solo le identità del dispositivo per abilitare l'accesso sicuro all'hub. Archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza e un flag di attivazione/disattivazione che consente di disabilitare l'accesso per un singolo dispositivo. Se l'applicazione deve archiviare altri metadati specifici del dispositivo, dovrà usare un archivio specifico dell'applicazione. Per altre informazioni, vedere la Guida per gli sviluppatori dell'hub IoT.

Se invece si desidera creare l'identità del dispositivo a livello di codice, leggere la sezione corrispondente nell'articolo Connettere il dispositivo simulato all'hub IoT tramite .NET.

Creare l'app di servizio

In questa sezione si crea un'app console .NET (usando C#) e si aggiungono i metadati della posizione al dispositivo gemello associato a myDeviceId. Viene quindi eseguita una query nei dispositivi gemelli archiviati nell'hub IoT selezionando i dispositivi situati negli Stati Uniti e quindi quelli che segnalano una rete cellulare.

  1. In Visual Studio aggiungere un progetto desktop di Windows classico in Visual C# usando il modello di progetto Applicazione console . Assegnare al progetto il nome AddTagsAndQuery.

    Nuovo progetto desktop di Windows classico in Visual C#

  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto AddTagsAndQuery e quindi fare clic su Gestisci pacchetti NuGet.
  3. Nella finestra Gestisci pacchetti NuGet selezionare Sfoglia e cercare microsoft.azure.devices. Selezionare Installa per installare il pacchetto Microsoft.Azure.Devices e accettare le condizioni per l'utilizzo. Questa procedura scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT - SDK per dispositivi e alle relative dipendenze.

    Finestra Gestione pacchetti NuGet

  4. Aggiungere le istruzione using seguenti all'inizio del file Program.cs :

     using Microsoft.Azure.Devices;
    
  5. Aggiungere i campi seguenti alla classe Program . Sostituire il valore del segnaposto con la stringa di connessione dell'hub IoT creato nella sezione precedente.

     static RegistryManager registryManager;
     static string connectionString = "{iot hub connection string}";
    
  6. Aggiungere il metodo seguente alla classe Program :

     public static async Task AddTagsAndQuery()
     {
         var twin = await registryManager.GetTwinAsync("myDeviceId");
         var patch =
             @"{
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                     }
                 }
             }";
         await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
    
         var query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         var twinsInRedmond43 = await query.GetNextAsTwinAsync();
         Console.WriteLine("Devices in Redmond43: {0}", string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));
    
         query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
         Console.WriteLine("Devices in Redmond43 using cellular network: {0}", string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
     }
    

    L'oggetto RegistryManager espone tutti i metodi necessari per interagire con i dispositivi gemelli dal servizio. Il codice precedente inizializza prima di tutto l'oggetto registryManager, quindi recupera il dispositivo gemello per myDeviceId e infine ne aggiorna i tag con le informazioni sulla posizione desiderate.

    Dopo l'aggiornamento, il codice precedente esegue due query: la prima seleziona solo i dispositivi gemelli tra quelli situati nello stabilimento Redmond43 e la seconda affina la query per selezionare solo i dispositivi che sono connessi anche tramite la rete cellulare.

    Si noti che il codice precedente, quando crea l'oggetto query, specifica un numero massimo di documenti restituiti. L'oggetto query contiene una proprietà booleana HasMoreResults che è possibile usare per richiamare i metodi GetNextAsTwinAsync più volte per recuperare tutti i risultati. Per i risultati che non sono dispositivi gemelli, ad esempio i risultati delle query di aggregazione, è disponibile un metodo chiamato GetNextAsJson.

  7. Aggiungere infine le righe seguenti al metodo Main :

     registryManager = RegistryManager.CreateFromConnectionString(connectionString);
     AddTagsAndQuery().Wait();
     Console.WriteLine("Press Enter to exit.");
     Console.ReadLine();
    
  8. In Esplora soluzioni aprire Imposta progetti di avvio e assicurarsi che Azione per il progetto AddTagsAndQuery sia impostata su Avvio. Compilare la soluzione.

  9. Eseguire l'applicazione facendo clic con il pulsante destro del mouse sul progetto AddTagsAndQuery e selezionando Debug, seguito da Avvia nuova istanza. Nei risultati si noterà un dispositivo per la query che cerca tutti i dispositivi situati in Redmond43 e nessuno per la query che limita i risultati ai dispositivi che usano una rete cellulare.

    Risultati della query nella finestra

Nella sezione successiva si crea un'app per dispositivo che segnala le informazioni sulla connettività e modifica il risultato della query nella sezione precedente.

Creare l'app per dispositivo

In questa sezione si crea un'app console .NET che si connette all'hub come myDeviceId e quindi aggiorna le proprietà segnalate per poter contenere le informazioni relative alla connessione usando una rete cellulare.

  1. In Visual Studio aggiungere un progetto desktop di Windows classico in Visual C# usando il modello di progetto Applicazione console . Denominare il progetto ReportConnectivity.

    Nuova app per il dispositivo di Windows classico in Visual C#

  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto ReportConnectivity, quindi fare clic su Gestisci pacchetti NuGet....

  3. Nella finestra Gestione pacchetti NuGet selezionare Sfoglia e cercare microsoft.azure.devices.client. Selezionare Installa per installare il pacchetto microsoft.azure.devices.client e accettare le condizioni d'uso. Questa procedura scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT SDK per dispositivi e alle relative dipendenze.

    App client della finestra Gestione pacchetti NuGet

  4. Aggiungere le istruzione using seguenti all'inizio del file Program.cs :

     using Microsoft.Azure.Devices.Client;
     using Microsoft.Azure.Devices.Shared;
     using Newtonsoft.Json;
    
  5. Aggiungere i campi seguenti alla classe Program . Sostituire il valore del segnaposto con la stringa di connessione del dispositivo annotato nella sezione precedente.

     static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
     static DeviceClient Client = null;
    
  6. Aggiungere il metodo seguente alla classe Program :

    public static async void InitClient()
     {
         try
         {
             Console.WriteLine("Connecting to hub");
             Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, TransportType.Mqtt);
             Console.WriteLine("Retrieving twin");
             await Client.GetTwinAsync();
         }
         catch (Exception ex)
         {
             Console.WriteLine();
             Console.WriteLine("Error in sample: {0}", ex.Message);
         }
     }
    

    L'oggetto Client espone tutti i metodi necessari per interagire con i dispositivi gemelli dal dispositivo. Il codice riportato sopra inizializza l'oggetto Client e quindi recupera il dispositivo gemello per myDeviceId.

  7. Aggiungere il metodo seguente alla classe Program :

     public static async void ReportConnectivity()
     {
         try
         {
             Console.WriteLine("Sending connectivity data as reported property");
    
             TwinCollection reportedProperties, connectivity;
             reportedProperties = new TwinCollection();
             connectivity = new TwinCollection();
             connectivity["type"] = "cellular";
             reportedProperties["connectivity"] = connectivity;
             await Client.UpdateReportedPropertiesAsync(reportedProperties);
         }
         catch (Exception ex)
         {
             Console.WriteLine();
             Console.WriteLine("Error in sample: {0}", ex.Message);
         }
     }
    

    Il codice sopra riportato aggiorna le proprietà segnalate di myDeviceId con le informazioni di connettività.

  8. Aggiungere infine le righe seguenti al metodo Main :

    try
    {
         InitClient();
         ReportConnectivity();
    }
    catch (Exception ex)
    {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
    }
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  9. In Esplora soluzioni aprire Imposta progetti di avvio... e assicurarsi che Azione per il progetto ReportConnectivity sia impostato su Avvio. Compilare la soluzione.

  10. Eseguire l'applicazione facendo clic con il pulsante destro del mouse sul progetto ReportConnectivity e selezionando Debug, seguito da Avvia nuova istanza. Si dovrebbero vedere le informazioni gemelle e quindi l'invio della connettività come proprietà segnalata.

    Eseguire l'app per dispositivi per segnalare la connettività

  11. Ora che il dispositivo ha segnalato le informazioni sulla connettività, verrà visualizzato in entrambe le query. Eseguire l'app .NET AddTagsAndQuery per eseguire nuovamente la query. Questa volta myDeviceId verrà visualizzato nei risultati di entrambe le query.

    Connettività del dispositivo segnalata correttamente

Passaggi successivi

In questa esercitazione è stato configurato un nuovo hub IoT nel Portale di Azure ed è stata quindi creata un'identità del dispositivo nel registro di identità dell'hub IoT. Sono stati aggiunti i metadati del dispositivo come tag da un'app back-end ed è stata scritta un'app per dispositivo simulato per segnalare le informazioni sulla connettività del dispositivo nel dispositivo gemello. Si è anche appreso come effettuare una query di queste informazioni usando il linguaggio di query simile a SQL dell'hub IoT.

Per altre informazioni, vedere le risorse seguenti: