Introducción a la identidad de módulo y a los módulos gemelos de IoT Hub (.NET)

Artículo
10/01/2024

Las identidades de módulo y los módulos gemelos son similares a la identidad de dispositivo y el dispositivo gemelo de Azure IoT Hub, pero ofrecen granularidad más fina. Aunque la identidad del dispositivo y los dispositivos gemelos de Azure IoT Hub permiten que la aplicación back-end configure un dispositivo y proporcionan visibilidad sobre las condiciones de este, la identidad del módulo y los módulos gemelos proporcionan estas funcionalidades para los componentes individuales de un dispositivo. En los dispositivos compatibles con varios componentes, como dispositivos con sistema operativo o firmware, identidades de módulo y módulos gemelos permiten la configuración individual y condiciones específicas por componente.

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Al final de este artículo, tendrá dos aplicaciones de consola de .NET:

CreateIdentities, crea una identidad de dispositivo, una de módulo y la clave de seguridad asociada para conectar el dispositivo y los clientes del módulo.
UpdateModuleTwinReportedProperties, envía las propiedades notificadas por el módulo gemelo actualizadas a IoT Hub.

Nota

Consulte los SDK de Azure IoT para obtener más información sobre las herramientas de SDK disponibles para compilar aplicaciones de dispositivo y back-end.

Requisitos previos

Visual Studio.
Una instancia de IoT Hub en la suscripción de Azure. Si aún no tiene un centro, puede seguir los pasos descritos en Creación de un centro de IoT.

Autenticación de módulos

Puede utilizar claves simétricas o certificados X.509 para autenticar las identidades de los módulos. Para la autenticación de certificados X.509, el certificado del módulo debe tener su nombre común (CN) formateado como CN=<deviceid>/<moduleid>. Por ejemplo:

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

Obtención de la cadena de conexión de IoT Hub

En este artículo, va a crear un servicio back-end que agregará un dispositivo en el registro de identidades y, a continuación, agregará un módulo a ese dispositivo. El servicio requiere el permiso de escribir en el Registro. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada registryReadWrite que concede este permiso.

Para obtener la cadena de conexión de IoT Hub para la directiva registryReadWrite, siga estos pasos:

En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.
En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.
En la lista de directivas, seleccione la directiva registryReadWrite.
Copie la Cadena de conexión principal y guarde el valor.

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Creación de una identidad de módulo

En esta sección se crea una aplicación de consola .NET que crea una identidad de dispositivo y otra de módulo en el registro de identidades del centro. No se puede conectar un dispositivo o un módulo al centro a menos que tenga una entrada en el registro de identidades. Para más información, consulte la sección sobre el registro de la identidad de la guía para desarrolladores de IoT Hub.

Cuando se ejecuta esta aplicación de consola, genera una clave y un identificador únicos para el dispositivo y el módulo. El dispositivo y el módulo usan estos valores para identificarse al enviar mensajes del dispositivo a la nube a IoT Hub. Los identificadores distinguen mayúsculas de minúsculas.

Abra Visual Studio y seleccione Crear un proyecto.
En Crear un proyecto, seleccione Aplicación de consola (.NET Framework).
Seleccione Siguiente para abrir Configurar el nuevo proyecto. Asigne al proyecto el nombre de CreateIdentities y, a continuación, seleccione Siguiente.
Mantenga la opción predeterminada de .NET Framework y seleccione Crear para crear su proyecto.
En Visual Studio, abra Herramientas>Administrador de paquetes NuGet>Administrar paquetes NuGet para la solución. Seleccione la pestaña Examinar.
Busque Microsoft.Azure.Devices. Selecciónelo y, a continuación, seleccione Instalar.

Agregue las siguientes instrucciones using al principio del archivo Program.cs :

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

Agregue los campos siguientes a la clase Program . Sustituya el valor de marcador de posición por la cadena de conexión de IoT Hub para el centro que creó en la sección anterior.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Agregue el siguiente código al final de la clase Main.

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

Agregue los métodos siguientes a la clase 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);
}
```
El método AddDeviceAsync crea una identidad del dispositivo con el identificador myFirstDevice. Si el identificador de dispositivo ya existe en el registro de identidades, el código simplemente recupera la información existente del dispositivo. A continuación, la aplicación muestra la clave principal de esa identidad. Esta clave se usará en la aplicación de dispositivo simulado para conectarse al centro.

El método AddModuleAsync crea una identidad de módulo con el identificador myFirstModule en el dispositivo myFirstDevice. Si el identificador de módulo ya existe en el registro de identidades, el código simplemente recupera la información existente del módulo. A continuación, la aplicación muestra la clave principal de esa identidad. Esta clave se usará en la aplicación de módulo simulado para conectarse al centro.

Importante

El identificador del dispositivo puede estar visible en los registros recopilados para soporte técnico y solución de problemas del cliente, por tanto asegúrese de evitar cualquier información confidencial al darle el nombre.
Ejecute la aplicación y anote la clave del dispositivo y del módulo.

Nota

El registro de identidades de IoT Hub solo almacena identidades de dispositivos y módulos para permitir el acceso seguro al centro. El registro de identidades almacena los identificadores y las claves de dispositivo para usarlas como credenciales de seguridad. El registro de identidades también almacena una marca de habilitado o deshabilitado de cada dispositivo que se puede usar para deshabilitar el acceso a dicho dispositivo. Si la aplicación necesita almacenar otros metadatos específicos del dispositivo, debe usar un almacén específico de la aplicación. No hay marcas de habilitado/deshabilitado para las identidades de módulo. Consulte la guía de desarrolladores de IoT Hub para obtener más información.

Actualización del módulo gemelo con el SDK de dispositivo .NET

Ahora vamos a comunicarnos a la nube desde tu dispositivo simulado. Al crearse una identidad de módulo, se crea también un módulo gemelo en IoT Hub de manera implícita. En esta sección se crea una aplicación de consola .NET en el dispositivo simulado que actualiza las propiedades notificadas del módulo gemelo.

Para recuperar la cadena de conexión del módulo, vaya a IoT Hub y seleccione Dispositivos. Busque y seleccione myFirstDevice para abrirlo y, a continuación, seleccione myFirstModule para abrirlo. En Detalles de identidad del módulo, copie la cadena de conexión (clave principal) y guárdela para la aplicación de consola.

Importante

En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de > Seguridad de la conexión.

En Visual Studio, agregue un nuevo proyecto a la solución; para ello, seleccione Archivo>Nuevo>Proyecto. En Crear un proyecto nuevo, seleccione Aplicación de consola (.NET Framework) y seleccione Siguiente.
En Configure un proyecto nuevo, asigne al proyecto el nombre de UpdateModuleTwinReportedProperties y seleccione Siguiente.
Mantenga la opción predeterminada de .NET Framework y seleccione Crear para crear su proyecto.
En Visual Studio, abra Herramientas>Administrador de paquetes NuGet>Administrar paquetes NuGet para la solución. Seleccione la pestaña Examinar.
Busque y seleccione Microsoft. Azure.Devices.Client y, después, Instalar.

Agregue las siguientes instrucciones using al principio del archivo Program.cs :

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

Agregue los campos siguientes a la clase Program . Reemplace el valor del marcador de posición por la cadena de conexión del módulo.

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

Agregue el método OnDesiredPropertyChanged siguiente a la clase 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);
    }

Agregue las líneas siguientes al método 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();
}

Ahora ya sabe cómo recuperar el módulo gemelo y actualizar las propiedades reportadas con el protocolo AMQP.

Opcionalmente, puede agregar estas instrucciones al método Main para enviar un evento al IoT Hub desde el módulo. Coloque estas líneas debajo del bloque 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.");

Ejecución de las aplicaciones

Ahora puede ejecutar las aplicaciones.

En Visual Studio, en el Explorador de soluciones, haga clic con el botón derecho en la solución y seleccione Establecer proyectos de inicio.
Seleccione Propiedades comunes y Proyecto de inicio.
Seleccione Proyectos de inicio múltiples y después Iniciar como acción para la aplicación y Aceptar para aceptar los cambios.
Presione F5 para iniciar las aplicaciones.

Pasos siguientes

Para continuar la introducción a IoT Hub y explorar otros escenarios de IoT, consulte:

Compartir vía

Introducción a la identidad de módulo y a los módulos gemelos de IoT Hub (.NET)

Requisitos previos

Autenticación de módulos

Obtención de la cadena de conexión de IoT Hub

Creación de una identidad de módulo

Actualización del módulo gemelo con el SDK de dispositivo .NET

Ejecución de las aplicaciones

Pasos siguientes

Comentarios

Recursos adicionales