Introduzione all'identità del modulo dell'hub IoT e al modulo gemello (.NET)
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. Mentre l'identità del dispositivo e il dispositivo gemello dell'hub IoT di Azure consentono all'applicazione back-end di configurare un dispositivo e forniscono visibilità sulle condizioni del dispositivo, l'identità del modulo e il modulo gemello forniscono queste funzionalità per i singoli componenti di un dispositivo. Nei dispositivi con più componenti, ad esempio i dispositivi di sistema operativo o i dispositivi firmware, le identità e i gemelli dei moduli permettono 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 Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.
Al termine di questo articolo si avranno due app console .NET:
CreateIdentities: crea un'identità del dispositivo, un'identità del modulo e una chiave di sicurezza associata per connettere i client dispositivo e modulo.
UpdateModuleTwinReportedProperties: invia le proprietà segnalate aggiornate del modulo gemello all'hub IoT.
Nota
Vedere Azure IoT SDK per altre informazioni sugli strumenti SDK disponibili per creare app sia per dispositivi che back-end.
Visual Studio.
Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.
È 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"
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 Scrittura registro. Per impostazione predefinita, ogni hub IoT viene creato con un criterio di accesso condiviso denominato registryReadWrite che concede tale 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.
Importante
Questo articolo include la procedura per connettersi a un servizio usando una firma di accesso condiviso. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione a un servizio con Microsoft Entra ID o identità gestite rappresenta un approccio più sicuro. Per altre informazioni, vedere Procedure consigliate per la sicurezza > Sicurezza cloud.
In questa sezione si crea un'app console .NET che crea un'identità del dispositivo e un'identità del modulo nel registro delle identità dell'hub IoT. Un dispositivo o un modulo non può connettersi all'hub IoT se non ha una voce nel registro delle identità. Per altre informazioni, vedere la sezione Registro di identità della Guida per gli sviluppatori dell'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 inviano messaggi da dispositivo a cloud all'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, quindi selezionare Avanti.
Mantenere l'opzione predefinita di .NET Framework e selezionare Crea per creare il progetto.
In Visual Studio aprire Strumenti>Gestione pacchetti 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 metodo
AddDeviceAsync
crea un'identità del dispositivo con ID myFirstDevice. Se questo ID dispositivo è già presente 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 verrà usata dall'app per dispositivo simulato per connettersi all'hub.Il metodo
AddModuleAsync
crea un'identità del modulo con ID myFirstModule nel dispositivo myFirstDevice. Se questo ID modulo è già presente nel registro delle identità, il codice recupera semplicemente le informazioni esistenti sul modulo. L'app visualizzerà quindi la chiave primaria per l'identità. Questa chiave verrà usata dall'app per modulo simulato 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 includere informazioni sensibili nel nome assegnato.
Eseguire l'app e prendere nota della chiave del dispositivo e della chiave del modulo.
Nota
Il registro delle identità dell'hub IoT archivia solo le identità del dispositivo e del modulo 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, dovrà 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.
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 quindi selezionare Dispositivi. Trovare e selezionare myFirstDevice per aprirlo e quindi selezionare myFirstModule per aprirlo. In Dettagli identità del modulocopiare la Stringa di connessione (chiave primaria) e salvarla per l'app console.
Importante
Questo articolo include la procedura per connettere un dispositivo usando una firma di accesso condiviso, altrimenti chiamata autenticazione con chiave simmetrica. Questo metodo di autenticazione è comodo per i test e le valutazioni, ma l'autenticazione tramite certificati X.509 rappresenta un approccio più sicuro. Per scoprire di più, vedere Procedure consigliate per la sicurezza > Sicurezza della connessione.
In Visual Studio aggiungere un nuovo progetto alla soluzione selezionando 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 UpdateModuleTwinReportedProperties e quindi selezionare Avanti.
Mantenere l'opzione predefinita di .NET Framework e selezionare Crea per creare il progetto.
In Visual Studio aprire Strumenti>Gestione pacchetti 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 nel 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 conosce 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 all'hub IoT dal modulo. Posizionare queste righe sotto il blocco
try catch
.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.");
È ora possibile eseguire le app.
In Esplora soluzioni di Visual Studio fare clic con il pulsante destro del mouse sulla soluzione e scegliere Imposta progetti di avvio.
In Proprietà comuni selezionare Progetto di avvio.
Selezionare Progetti di avvio multipli e quindi selezionare Avvia come azione per le app e OK per accettare le modifiche.
Premere F5 per avviare le app.
Per altre informazioni sulle attività iniziali con l'hub IoT e per esplorare altri scenari IoT, vedere: