Introduzione ai dispositivi gemelli (.NET/Node)Get started with device twins (.NET/Node)

I dispositivi gemelli sono documenti JSON nei quali vengono archiviate informazioni sullo stato dei dispositivi (metadati, configurazioni e condizioni).Device twins are JSON documents that store device state information (metadata, configurations, and conditions). L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.IoT Hub persists a device twin for each device that connects to it.

Usare i dispositivi gemelli per:Use device twins to:

  • Archiviare i metadati dei dispositivi dal back-end della soluzione.Store device metadata from your solution back end.
  • Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi.Report current state information such as available capabilities and conditions (for example, the connectivity method used) from your device app.
  • 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.Synchronize the state of long-running workflows (such as firmware and configuration updates) between a device app and a back-end app.
  • Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.Query your device metadata, configuration, or state.

Nota

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi.Device twins are designed for synchronization and for querying device configurations and conditions. Altre informazioni su quando usare i dispositivi gemelli sono reperibili in Informazioni sui dispositivi gemelli.More informations on when to use device twins can be found in Understand device twins.

I dispositivi gemelli vengono archiviati in un hub IoT e contengono gli elementi seguenti.Device twins are stored in an IoT hub and contain:

  • Tag: metadati dei dispositivi accessibili solo dal back-end della soluzionetags, device metadata accessible only by the solution back end;
  • Proprietà desiderate: oggetti JSON modificabili dal back-end della soluzione e osservabili dall'app per dispositividesired properties, JSON objects modifiable by the solution back end and observable by the device app; and
  • Proprietà segnalate: oggetti JSON modificabili dall'app per dispositivi e leggibili dal back-end della soluzionereported properties, JSON objects modifiable by the device app and readable by the solution back end. I tag e le proprietà non possono contenere matrici, ma gli oggetti possono essere annidati.Tags and properties cannot contain arrays, but objects can be nested.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati.Additionally, the solution back end can query device twins based on all the above data. Vedere Informazioni sui dispositivi gemelli per altre informazioni sui dispositivi gemelli e Linguaggio di query per hub IoT per informazioni sull'esecuzione di query.Refer to Understand device twins for more information about device twins, and to the IoT Hub query language reference for querying.

Questa esercitazione illustra come:This tutorial shows you how to:

  • 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.Create a back-end app that adds tags to a device twin, and a simulated device app that reports its connectivity channel as a reported property on the device twin.
  • Eseguire query sui dispositivi dall'app back-end con filtri sui tag e sulle proprietà creati in precedenza.Query devices from your back-end app using filters on the tags and properties previously created.

Con questa esercitazione vengono create un'app console Node.js e un'app console .NET:At the end of this tutorial, you will have a .NET and a Node.js console app:

  • AddTagsAndQuery.sln, un'app back-end .NET, che aggiunge tag ed effettua una query dei dispositivi gemelli.AddTagsAndQuery.sln, a .NET back-end app, which adds tags and queries device twins.
  • TwinSimulatedDevice.js, un'app Node.js che simula un dispositivo che si connette all'hub IoT con l'identità del dispositivo creata prima e segnala la condizione della connettività.TwinSimulatedDevice.js, a Node.js app which simulates a device that connects to your IoT hub with the device identity created earlier, and reports its connectivity condition.

Nota

L'articolo Azure IoT SDK contiene informazioni sui componenti Azure IoT SDK che consentono di compilare le app back-end e per dispositivi.The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-end apps.

Per completare l'esercitazione, sono necessari gli elementi seguenti:To complete this tutorial you need the following:

  • Visual Studio 2015 o Visual Studio 2017.Visual Studio 2015 or Visual Studio 2017.
  • Node.js 4.0.x o versione successiva.Node.js version 4.0.x or later.
  • Un account Azure attivo.An active Azure account. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.(If you don't have an account, you can create a free account in just a couple of minutes.)

Creare un hub IoTCreate an IoT hub

Creare un hub IoT per connettere l'app per dispositivo simulato.Create an IoT hub for your simulated device app to connect to. La procedura seguente illustra come completare questa attività usando il portale di Azure.The following steps show you how to complete this task by using the Azure portal.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Selezionare Nuovo > Internet delle cose > Hub IoT.Select New > Internet of Things > IoT Hub.

    Indice del portale di Azure

  3. Nel riquadro Hub IoT immettere le informazioni seguenti per l'hub IoT:In the IoT hub pane, enter the following information for your IoT hub:

    • Nome: creare un nome per l'hub IoT.Name: Create a name for your IoT hub. Se il nome immesso è valido, viene visualizzato un segno di spunta verde.If the name you enter is valid, a green check mark appears.

    Importante

    L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.The IoT hub will be publicly discoverable as a DNS endpoint, so make sure to avoid any sensitive information while naming it.

    • Piano tariffario e livello di scalabilità: per questa esercitazione selezionare il livello F1 gratuito.Pricing and scale tier: For this tutorial, select the F1 - Free tier. Per altre informazioni, vedere la pagina relativa a piano tariffario e livello di scalabilità.For more information, see the Pricing and scale tier.

    • Gruppo di risorse: creare un gruppo di risorse per ospitare l'hub IoT o usarne uno esistente.Resource group: Create a resource group to host the IoT hub or use an existing one. Per altre informazioni, vedere l'articolo su come usare i gruppi di risorse per gestire le risorse di Azure.For more information, see Use resource groups to manage your Azure resources

    • Località: selezionare la località più vicina.Location: Select the closest location to you.

    • Aggiungi al dashboard: selezionare questa opzione per semplificare l'accesso all'hub IoT dal dashboard.Pin to dashboard: Check this option for easy access to your IoT hub from the dashboard.

      Finestra Hub IoT

  4. Fare clic su Crea.Click Create. La creazione dell'hub IoT può richiedere alcuni minuti.Your IoT hub might take a few minutes to create. È possibile monitorare lo stato di avanzamento nel riquadro Notifiche.You can monitor the progress in the Notifications pane.

Ora che è stato creato un hub IoT, individuare le informazioni importanti che consentono di connettere dispositivi e applicazioni all'hub IoT.Now that you have created an IoT hub, locate the important information that you use to connect devices and applications to your IoT hub.

  1. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro dell'hub IoT nel portale di Azure per aprire la finestra delle proprietà.When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to open the properties window for the new IoT hub. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.Make a note of the Hostname, and then click Shared access policies.

    Finestra del nuovo hub IoT

  2. In Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nella finestra iothubowner.In Shared access policies, click the iothubowner policy, and then copy and make note of the IoT Hub connection string in the iothubowner window. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".For more information, see Access control in the "IoT Hub developer guide."

    Criteri di accesso condivisi

Creare un'identità del dispositivoCreate a device identity

In questa sezione si usa uno strumento di Node.js denominato iothub-explorer per creare un'identità del dispositivo per questa esercitazione.In this section, you use a Node.js tool called iothub-explorer to create a device identity for this tutorial. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.Device IDs are case sensitive.

  1. Eseguire il codice seguente nell'ambiente della riga di comando:Run the following in your command-line environment:

    npm install -g iothub-explorer@latest

  2. Eseguire quindi il comando indicato di seguito per accedere all'hub.Then, run the following command to login to your hub. Sostituire {iot hub connection string} con la stringa di connessione all'hub IoT copiata prima:Substitute {iot hub connection string} with the IoT Hub connection string you previously copied:

    iothub-explorer login "{iot hub connection string}"

  3. Creare infine una nuova identità del dispositivo denominata myDeviceId con il comando:Finally, create a new device identity called myDeviceId with the command:

    iothub-explorer create myDeviceId --connection-string

    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.The device ID may be visible in the logs collected for customer support and troubleshooting, so make sure to avoid any sensitive information while naming it.

Annotare la stringa di connessione del dispositivo visualizzata nei risultati.Make a note of the device connection string from the result. Questa stringa di connessione del dispositivo viene usata dall'app del dispositivo per la connessione all'hub IoT come dispositivo.This device connection string is used by the device app to connect to your IoT Hub as a device.

Per creare identità del dispositivo a livello di codice, vedere Introduzione all'hub IoT.Refer to Getting started with IoT Hub to programmatically create device identities.

Creare l'app di servizioCreate the service app

In questa sezione si crea un'app console .NET (usando C#) e si aggiungono i metadati della posizione al dispositivo gemello associato a myDeviceId.In this section, you create a .NET console app (using C#) that adds location metadata to the device twin associated with 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.It then queries the device twins stored in the IoT hub selecting the devices located in the US, and then the ones that reported a cellular connection.

  1. In Visual Studio aggiungere un progetto desktop di Windows classico in Visual C# usando il modello di progetto Applicazione console .In Visual Studio, add a Visual C# Windows Classic Desktop project to the current solution by using the Console Application project template. Assegnare al progetto il nome AddTagsAndQuery.Name the project 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.In Solution Explorer, right-click the AddTagsAndQuery project, and then click Manage NuGet Packages....
  3. Nella finestra Gestisci pacchetti NuGet selezionare Sfoglia e cercare microsoft.azure.devices.In the NuGet Package Manager window, select Browse and search for microsoft.azure.devices. Selezionare Installa per installare il pacchetto Microsoft.Azure.Devices e accettare le condizioni per l'utilizzo.Select Install to install the Microsoft.Azure.Devices package, and accept the terms of use. Questa procedura scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT - SDK per dispositivi e alle relative dipendenze.This procedure downloads, installs, and adds a reference to the Azure IoT service SDK NuGet package and its dependencies.

    Finestra Gestione pacchetti NuGet

  4. Aggiungere le istruzione using seguenti all'inizio del file Program.cs :Add the following using statements at the top of the Program.cs file:

     using Microsoft.Azure.Devices;
    
  5. Aggiungere i campi seguenti alla classe Program .Add the following fields to the Program class. Sostituire il valore del segnaposto con la stringa di connessione dell'hub IoT creato nella sezione precedente.Replace the placeholder value with the IoT Hub connection string for the hub that you created in the previous section.

     static RegistryManager registryManager;
     static string connectionString = "{iot hub connection string}";
    
  6. Aggiungere il metodo seguente alla classe Program :Add the following method to the Program class:

     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.The RegistryManager class exposes all the methods required to interact with device twins from the service. 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.The previous code first initializes the registryManager object, then retrieves the device twin for myDeviceId, and finally updates its tags with the desired location information.

    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.After updating, it executes two queries: the first selects only the device twins of devices located in the Redmond43 plant, and the second refines the query to select only the devices that are also connected through cellular network.

    Si noti che il codice precedente, quando crea l'oggetto query, specifica un numero massimo di documenti restituiti.Note that the previous code, when it creates the query object, specifies a maximum number of returned documents. L'oggetto query contiene una proprietà booleana HasMoreResults che è possibile usare per richiamare i metodi GetNextAsTwinAsync più volte per recuperare tutti i risultati.The query object contains a HasMoreResults boolean property that you can use to invoke the GetNextAsTwinAsync methods multiple times to retrieve all results. Per i risultati che non sono dispositivi gemelli, ad esempio i risultati delle query di aggregazione, è disponibile un metodo chiamato GetNextAsJson.A method called GetNextAsJson is available for results that are not device twins, for example, results of aggregation queries.

  7. Aggiungere infine le righe seguenti al metodo Main :Finally, add the following lines to the Main method:

     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.In the Solution Explorer, open the Set StartUp projects... and make sure the Action for AddTagsAndQuery project is Start. Compilare la soluzione.Build the solution.

  9. Eseguire l'applicazione facendo clic con il pulsante destro del mouse sul progetto AddTagsAndQuery e selezionando Debug, seguito da Avvia nuova istanza.Run this application by right-clicking on the AddTagsAndQuery project and selecting Debug, followed by Start new instance. 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.You should see one device in the results for the query asking for all devices located in Redmond43 and none for the query that restricts the results to devices that use a cellular network.

    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.In the next section, you create a device app that reports the connectivity information and changes the result of the query in the previous section.

Creare l'app per dispositivoCreate the device app

In questa sezione si crea un'app console Node.js 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.In this section, you create a Node.js console app that connects to your hub as myDeviceId, and then updates its reported properties to contain the information that it is connected using a cellular network.

  1. Creare una nuova cartella vuota denominata reportconnectivity.Create a new empty folder called reportconnectivity. Nella cartella reportconnectivity creare un nuovo file package.json immettendo il comando seguente al prompt dei comandi.In the reportconnectivity folder, create a new package.json file using the following command at your command prompt. Accettare tutte le impostazioni predefinite.Accept all the defaults.

    npm init
    
  2. Eseguire questo comando al prompt dei comandi nella cartella reportconnectivity per installare i pacchetti azure-iot-device e azure-iot-device-mqtt:At your command prompt in the reportconnectivity folder, run the following command to install the azure-iot-device, and azure-iot-device-mqtt package:

    npm install azure-iot-device azure-iot-device-mqtt --save
    
  3. Usando un editor di testo, creare un nuovo file ReportConnectivity.js nella cartella reportconnectivity.Using a text editor, create a new ReportConnectivity.js file in the reportconnectivity folder.
  4. Aggiungere il codice seguente al file ReportConnectivity.js e sostituire il segnaposto per la stringa di connessione al dispositivo con quello copiato quando è stata creata l'identità del dispositivo myDeviceId:Add the following code to the ReportConnectivity.js file, and substitute the placeholder for device connection string with the one you copied when you created the myDeviceId device identity:

     'use strict';
     var Client = require('azure-iot-device').Client;
     var Protocol = require('azure-iot-device-mqtt').Mqtt;
    
     var connectionString = '{device connection string}';
     var client = Client.fromConnectionString(connectionString, Protocol);
    
     client.open(function(err) {
     if (err) {
         console.error('could not open IotHub client');
     }  else {
         console.log('client opened');
    
         client.getTwin(function(err, twin) {
         if (err) {
             console.error('could not get twin');
         } else {
             var patch = {
                 connectivity: {
                     type: 'cellular'
                 }
             };
    
             twin.properties.reported.update(patch, function(err) {
                 if (err) {
                     console.error('could not update twin');
                 } else {
                     console.log('twin state reported');
                     process.exit();
                 }
             });
         }
         });
     }
     });
    

    L'oggetto Client espone tutti i metodi necessari per interagire con i dispositivi gemelli dal dispositivo.The Client object exposes all the methods you require to interact with device twins from the device. Il codice precedente, dopo avere inizializzato l'oggetto Client, recupera il dispositivo gemello per myDeviceId e aggiorna le proprietà segnalate con le informazioni sulla connettività.The previous code, after it initializes the Client object, retrieves the device twin for myDeviceId and updates its reported property with the connectivity information.

  5. Eseguire l'app per dispositivoRun the device app

     node ReportConnectivity.js
    

    Dovrebbe essere visualizzato il messaggio twin state reported.You should see the message twin state reported.

  6. Ora che il dispositivo ha segnalato le informazioni sulla connettività, verrà visualizzato in entrambe le query.Now that the device reported its connectivity information, it should appear in both queries. Eseguire l'app .NET AddTagsAndQuery per eseguire nuovamente la query.Run the .NET AddTagsAndQuery app to run the queries again. Questa volta myDeviceId verrà visualizzato nei risultati di entrambe le query.This time myDeviceId should appear in both query results.

Passaggi successiviNext steps

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.In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT hub's identity registry. 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.You added device metadata as tags from a back-end app, and wrote a simulated device app to report device connectivity information in the device twin. Si è anche appreso come effettuare una query di queste informazioni usando il linguaggio di query simile a SQL dell'hub IoT.You also learned how to query this information using the SQL-like IoT Hub query language.

Per altre informazioni, vedere le risorse seguenti:Use the following resources to learn how to: