Introduzione ai dispositivi gemelli (.NET)

Articolo
03/17/2023

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:

Screenshot di un diagramma del concetto di 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'app per dispositivo simulato per segnalare il 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.

In questo articolo vengono create due app console .NET:

AddTagsAndQuery: un'app back-end che aggiunge tag ed esegue query sui dispositivi gemelli.
Report Connessione ivity: un'app per dispositivi simulata che si connette all'hub IoT e ne segnala la condizione di connettività.

Nota

Vedere Azure IoT SDK per altre informazioni sugli strumenti SDK disponibili per creare app sia per dispositivi che back-end.

Prerequisiti

Visual Studio.
Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.
Un dispositivo registrato. Registrarne uno nel portale di Azure.
Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo 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).

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge le proprietà desiderate a un dispositivo gemello e quindi esegue una query nel registro delle identità per trovare tutti i dispositivi con le proprietà segnalate che sono stati aggiornati di conseguenza. Il servizio richiede l’autorizzazione di connessione al servizio per modificare le proprietà desiderate di un dispositivo gemello ed è necessaria l’autorizzazione di lettura del registro di sistema per eseguire query sul registro delle identità. Non esistono criteri di accesso condiviso predefiniti che contengono solo queste due autorizzazioni, quindi è necessario crearne uno.

Per creare criteri di accesso condiviso che concedono le autorizzazioni di connessione al servizio e lettura del registro di sistema e ottenere una stringa di connessione per questo criterio, attenersi alla seguente procedura:

Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.
Nel menu in alto sopra l'elenco dei criteri selezionare Aggiungi criteri di accesso ai criteri condivisi.
Nel riquadro Aggiungi criteri di accesso condiviso a destra immettere un nome descrittivo per i criteri, ad esempio serviceAndRegistryRead. In Autorizzazioni selezionare Lettura e servizio del Registro di sistema Connessione e quindi selezionare Aggiungi.
Selezionare il nuovo criterio dall'elenco dei criteri.
Selezionare l'icona di copia per il stringa di connessione primario e salvare il valore.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Creare un'app per dispositivi che aggiorna le proprietà segnalate

In questa sezione si crea un'app console .NET che si connette all'hub come myDeviceId e quindi aggiorna le proprietà segnalate per verificare che sia connessa usando una rete cellulare.

Aprire Visual Studio e selezionare Crea nuovo progetto.
Scegliere App console (.NET Framework) e quindi selezionare Avanti.
In Configura il nuovo progetto assegnare al progetto il nome Report Connessione ivity e quindi selezionare Avanti.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto ReportConnectivity, quindi selezionare Gestisci pacchetti NuGet.
Mantenere .NET Framework predefinito, quindi selezionare Crea per creare il progetto.
Selezionare Sfoglia e cercare e scegliere Microsoft.Azure.Devices.Client. Selezionare Installa.

Questo passaggio scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT SDK per dispositivi e alle relative dipendenze.

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Aggiungere i campi seguenti alla classe Program . Sostituire {device connection string} con il dispositivo stringa di connessione visualizzato quando è stato registrato un dispositivo nel hub IoT:
```
static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;
```

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.

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

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();

In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione e selezionare Imposta progetti di avvio.
In Proprietà comuni>Progetto di avvio, selezionare Progetti di avvio multipli. Per ReportConnectivity, selezionare Avvia come Azione. Selezionare OK per salvare le modifiche.
Eseguire l'app facendo clic con il pulsante destro del mouse sul progetto ReportConnectivity e selezionando Debug, seguito da Avvia nuova istanza. Si dovrebbe notare l'app che recupera le informazioni sui dispositivi gemelli e quindi l’invio della connettività come proprietà segnalata.

Dopo che il dispositivo ha segnalato le informazioni sulla connettività, verrà visualizzato in entrambe le query.
Fare clic con il pulsante destro del mouse sul progetto AddTagsAndQuery e selezionare Debug>Avvia nuova istanza per eseguire di nuovo le query. Questa volta myDeviceId verrà visualizzato nei risultati di entrambe le query.

Creare un'app di servizio che aggiorni le proprietà desiderate e le query dei dispositivi gemelli

In questa sezione si crea un'app console .NET usando C# e si aggiungono i metadati della posizione al dispositivo gemello associato a myDeviceId. L'app esegue una query sull'hub IoT per i dispositivi che si trovano negli Stati Uniti e quindi esegue query sui dispositivi che segnalano una connessione di rete cellulare.

In Visual Studio selezionare File > Nuovo > progetto. In Crea un nuovo progetto, selezionare App console (.NET Framework), quindi selezionare Avanti.
In Configura il nuovo progetto assegnare al progetto il nome AddTagsAndQuery, quindi selezionare Avanti.
Accettare la versione predefinita di .NET Framework, quindi selezionare Crea per creare il progetto.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto AddTagsAndQuery e quindi selezionare Gestisci pacchetti NuGet.
Selezionare Sfoglia e cercare e selezionare Microsoft. Azure. Devices. Selezionare Installa.

Questa procedura scarica, installa e aggiunge un riferimento al pacchetto NuGet Azure IoT SDK per servizi e alle relative dipendenze.
Aggiungere le istruzione using seguenti all'inizio del file Program.cs :
```
using Microsoft.Azure.Devices;
```
Aggiungere i campi seguenti alla classe Program . Sostituire {iot hub connection string} con la stringa di connessione dell'hub IoT copiata in Ottenere la stringa di connessione dell'hub IoT.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

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.

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.

Aggiungere infine le righe seguenti al metodo Main :

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

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.

In questo articolo si apprenderà come:

Aggiunta di metadati del dispositivo come tag da un'app back-end
Informazioni sulla connettività del dispositivo segnalate nel dispositivo gemello
Query sulle informazioni sul dispositivo gemello usando un linguaggio di query simile a SQL hub IoT

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.

Introduzione ai dispositivi gemelli (.NET)

Prerequisiti

Ottenere la stringa di connessione dell'hub IoT

Creare un'app per dispositivi che aggiorna le proprietà segnalate

Creare un'app di servizio che aggiorni le proprietà desiderate e le query dei dispositivi gemelli

Passaggi successivi

Risorse aggiuntive