Introduzione all'identità del modulo di hub IoT e al modulo gemello (.NET)

Articolo
08/25/2023

Le identità del modulo e i moduli gemelli sono simili alle identità del dispositivo e ai dispositivi gemelli dell'hub IoT di Azure, ma offrono una granularità superiore. Anche se hub IoT di Azure'identità del dispositivo e del dispositivo gemello consentono all'applicazione back-end di configurare un dispositivo e fornire visibilità sulle condizioni del dispositivo, un'identità del modulo e un modulo gemello forniscono queste funzionalità per singoli componenti di un dispositivo. Nei dispositivi compatibili con più componenti, ad esempio dispositivi del sistema operativo o dispositivi firmware, identità dei moduli e moduli gemelli consentono la configurazione e le condizioni isolate per ogni componente.

Nota

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

Alla fine di questo articolo sono disponibili due app console .NET:

CreateIdentities: crea un'identità del dispositivo, un'identità del modulo e una chiave di sicurezza associata per connettere i client del dispositivo e del modulo.
UpdateModuleTwinReportedProperties: invia i moduli gemelli aggiornati, le proprietà segnalate all'hub IoT.

Nota

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

Prerequisiti

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

Autenticazione del modulo

È possibile usare chiavi simmetriche o certificati X.509 per autenticare le identità del modulo. Per l'autenticazione del certificato X.509, il certificato del modulo deve avere il nome comune (CN) formattato come CN=<deviceid>/<moduleid>. Ad esempio:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge un dispositivo nel registro delle identità e quindi aggiunge un modulo a tale dispositivo. Il servizio richiede l'autorizzazione di scrittura del Registro di sistema . Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato RegistryReadWrite che concede questa autorizzazione.

Per ottenere la stringa di connessione dell'hub IoT per i criteri registryReadWrite, seguire questa 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.
Dall'elenco dei criteri selezionare il criterio registryReadWrite.
Copiare la stringa di connessione primaria 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'identità del modulo

In questa sezione viene creata un'app console .NET che crea un'identità del dispositivo e un'identità del modulo nel registro delle identità nell'hub. Un dispositivo o un modulo non può connettersi all'hub a meno che non abbia una voce nel registro delle identità. Per altre informazioni, vedere la sezione Registro di identità della guida per sviluppatori di hub IoT.

Quando si esegue questa app console vengono generati un ID e una chiave univoci sia per il dispositivo che per il modulo. Il dispositivo e il modulo usano questi valori per identificarsi quando invia messaggi da dispositivo a cloud a hub IoT. Negli ID viene fatta distinzione tra maiuscole e minuscole.

Aprire Visual Studio e selezionare Crea un nuovo progetto.
In Crea un nuovo progetto selezionare App console (.NET Framework).
Selezionare Avanti per aprire Configura il nuovo progetto. Assegnare al progetto il nome CreateIdentities e quindi selezionare Avanti.
Mantenere l'opzione predefinita .NET Framework e selezionare Crea per creare il progetto.
In Visual Studio aprire Strumenti> Gestionepacchetti>NuGet Gestisci pacchetti NuGet per la soluzione. Selezionare la scheda Sfoglia.
Cercare Microsoft.Azure.Devices. Selezionarlo e quindi selezionare Installa.

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

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

Aggiungere i campi seguenti alla classe Program . Sostituire il valore del segnaposto con la stringa di connessione dell'hub IoT creato nella sezione precedente.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Aggiungere il codice seguente alla classe Main.

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Aggiungere i metodi seguenti alla classe Program:

private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}

Il AddDeviceAsync metodo crea un'identità del dispositivo con ID myFirstDevice. Se l'ID dispositivo esiste già nel registro delle identità, il codice recupera semplicemente le informazioni sul dispositivo esistenti. L'app visualizzerà quindi la chiave primaria per l'identità. Questa chiave viene usata nell'app per dispositivi simulati per connettersi all'hub.

Il metodo crea un'identità del AddModuleAsync modulo con ID myFirstModule nel dispositivo myFirstDevice. Se tale ID modulo esiste già nel Registro di sistema delle identità, il codice recupera semplicemente le informazioni del modulo esistenti. L'app visualizzerà quindi la chiave primaria per l'identità. Questa chiave viene usata nell'app per moduli simulati per connettersi all'hub.

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.

Eseguire questa app e prendere nota della chiave del dispositivo e del modulo.

Nota

Il registro delle identità di hub IoT archivia solo le identità dei dispositivi e dei moduli per abilitare l'accesso sicuro all'hub. Il registro delle identità archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza. Il registro delle identità archivia anche un flag di abilitazione/disabilitazione per ogni dispositivo che consente di disabilitare l'accesso per un dispositivo. Se l'app deve archiviare altri metadati specifici del dispositivo, deve usare un archivio specifico dell'applicazione. Non esiste alcun flag abilitato/disabilitato per le identità del modulo. Per altre informazioni, vedere la Guida per gli sviluppatori dell'hub IoT.

Aggiornare il modulo gemello usando l'SDK per dispositivi .NET

A questo punto è possibile comunicare con il cloud dal dispositivo simulato. Una volta creata un'identità del modulo, viene implicitamente creato anche un modulo gemello nell'hub IoT. In questa sezione, nel dispositivo simulato viene creata un'app console .NET che aggiorna le proprietà segnalate del modulo gemello.

Per recuperare la stringa di connessione del modulo, passare all'hub IoT e quindi selezionare Dispositivi. Trovare e selezionare myFirstDevice per aprirlo e quindi selezionare myFirstModule per aprirlo. In Dettagli identità modulo copiare la stringa di connessione (chiave primaria) e salvarla per l'app console.

In Visual Studio aggiungere un nuovo progetto alla soluzione selezionando File>Nuovo>progetto. In Crea un nuovo progetto selezionare App console (.NET Framework) e selezionare Avanti.
In Configura il nuovo progetto assegnare al progetto il nome UpdateModuleTwinReportedProperties e quindi selezionare Avanti.
Mantenere l'opzione predefinita .NET Framework e selezionare Crea per creare il progetto.
In Visual Studio aprire Strumenti> Gestionepacchetti>NuGet Gestisci pacchetti NuGet per la soluzione. Selezionare la scheda Sfoglia.
Cercare e selezionare Microsoft.Azure.Devices.Client, quindi selezionare Installa.

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Aggiungere i campi seguenti alla classe Program . Sostituire il valore del segnaposto con la stringa di connessione del modulo.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

Aggiungere il metodo OnDesiredPropertyChanged seguente alla classe Program:

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Aggiungere le righe seguenti al metodo Main :

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

Ora si sa come recuperare il modulo gemello e aggiornare le proprietà segnalate con il protocollo AMQP.

Facoltativamente, è possibile aggiungere queste istruzioni al metodo Main per inviare un evento a hub IoT dal modulo. Posizionare queste righe sotto il try catch blocco.

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

Eseguire le app

È ora possibile eseguire le app.

In Visual Studio, in Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione e quindi scegliere Imposta progetti startup.
In Proprietà comuni selezionare Progetto di avvio.
Selezionare Più progetti di avvio e quindi selezionare Avvia come azione per le app e OK per accettare le modifiche.
Premere F5 per avviare le app.

Passaggi successivi

Per altre informazioni sulle attività iniziali con l'hub IoT e per esplorare altri scenari IoT, vedere:

Condividi tramite

Introduzione all'identità del modulo di hub IoT e al modulo gemello (.NET)

Prerequisiti

Autenticazione del modulo

Ottenere la stringa di connessione dell'hub IoT

Creare un'identità del modulo

Aggiornare il modulo gemello usando l'SDK per dispositivi .NET

Eseguire le app

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive