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

Artikulua
10/01/2024

Las identidades de módulo y los módulos gemelos son similares a las identidades de dispositivo y los dispositivos gemelos de Azure IoT Hub, pero ofrecen granularidad más fina. Aunque las identidades de dispositivo y los dispositivos gemelos de Azure IoT Hub permiten que una aplicación back-end configure un dispositivo y proporcionan visibilidad para las condiciones del dispositivo, las identidades de módulo y los módulos gemelos proporcionan estas funcionalidades para los componentes individuales del dispositivo. En los dispositivos compatibles con varios componentes, como dispositivos con sistema operativo o firmware, 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, tiene tres aplicaciones de Python:

CreateModule: crea una identidad de dispositivo, una de módulo y las claves de seguridad asociadas para conectar el dispositivo y los clientes del módulo.
UpdateModuleTwinDesiredProperties: envía las propiedades deseadas del módulo gemelo actualizadas a IoT Hub.
ReceiveModuleTwinDesiredPropertiesPatch: recibe la revisión de las propiedades deseadas del módulo gemelo en el dispositivo.

Nota

Para más información sobre las herramientas de SDK disponibles para compilar aplicaciones de dispositivo y back-end, consulte SDK de Azure IoT.

Requisitos previos

Una cuenta de Azure activa. (En caso de no tener ninguna, puede crear una cuenta gratuita en tan solo unos minutos).
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.
Se recomienda usar Python versión 3.7 o posterior. Asegúrese de usar la instalación de 32 bits o 64 bits en función del programa de instalación. Cuando se le solicite durante la instalación, asegúrese de agregar Python a la variable de entorno específica de la plataforma.

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. Este servicio requiere el permiso de escribir en el Registro (que también incluye el permiso de leer el Registro). También creará un servicio que agrega las propiedades deseadas al módulo gemelo del módulo recién creado. Este servicio necesita el permiso de conexión del servicio. Si bien hay directivas de acceso compartido predeterminadas que conceden estos permisos de forma individual, en esta sección se crea una directiva de acceso compartido personalizada que contiene ambos permisos.

Para crear una directiva de acceso compartido que conceda los permisos de conexión del servicio y escritura en el registro, y para obtener una cadena de conexión para esta directiva, 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 el menú situado encima de la lista de directivas, seleccione Agregar una directiva de acceso compartida.
En Agregar una directiva de acceso compartida, escriba un nombre descriptivo para la directiva, por ejemplo serviceAndRegistryReadWrite. En Permisos, seleccione Escribir en el registro y Conexión del servicio y, después, seleccione Agregar. (El permiso de Lectura del registro se incluye automáticamente cuando se selecciona Registry write [Escribir en el registro]).
Seleccione la directiva nueva en la lista de directivas.
En Claves de acceso compartido, seleccione el icono de copia de 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.

Crear una identidad del dispositivo y una identidad de módulo en IoT Hub

En esta sección se crea una aplicación de servicio de Python que crea a su vez una identidad de dispositivo y otra de módulo en el registro de identidades de la instancia de IoT Hub. No se puede conectar un dispositivo o un módulo a IoT Hub a menos que tenga una entrada en el registro de identidades. Para más información, consulte Descripción del registro de identidades de un centro de IoT. Cuando se ejecuta esta aplicación de consola, genera una clave y un identificador únicos para el dispositivo y el módulo. El identificador y la clave distinguen mayúsculas de minúsculas. El dispositivo y el módulo usan estos valores para identificarse al enviar mensajes del dispositivo a la nube a IoT Hub.

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 el símbolo del sistema, ejecute el siguiente comando para instalar el paquete azure-iot-hub:
```
pip install azure-iot-hub
```
En el símbolo del sistema, ejecute el siguiente comando para instalar el paquete msrest. Necesita este paquete para capturar excepciones HTTPOperationError.
```
pip install msrest
```
Con un editor de texto, cree un archivo denominado CreateModule.py en el directorio de trabajo.

Agregue el código siguiente al archivo de Python. Reemplace YourIoTHubConnectionString por la cadena de conexión que copió en Obtención de la cadena de conexión de IoT Hub.

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

except Exception as ex:
    print("Unexpected error {0}".format(ex))
except KeyboardInterrupt:
    print("IoTHubRegistryManager sample stopped")

En el símbolo del sistema, ejecute el comando siguiente:
```
python CreateModule.py
```

Esta aplicación crea una identidad del dispositivo con el identificador myFirstDevice y una de módulo con el identificador myFirstModule en el dispositivo myFirstDevice. (Si el id. del dispositivo o del módulo ya existe en el registro de identidades, el código simplemente recupera la información del dispositivo o módulo existente). La aplicación muestra el identificador y la clave principal de cada identidad.

Nota

El registro de identidades de IoT Hub solo almacena identidades de dispositivos y módulos para permitir el acceso seguro a IoT Hub. 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. Para más información, consulte Descripción del registro de identidades de un centro de IoT.

Actualización del módulo gemelo con el SDK del servicio de Python

En esta sección, creará una aplicación de servicio de Python que actualiza las propiedades deseadas del módulo gemelo.

En el símbolo del sistema, ejecute el comando siguiente para instalar el paquete azure-iot-hub. Puede omitir este paso si instaló el paquete azure-iot-hub en la sección anterior.
```
pip install azure-iot-hub
```
Con un editor de texto, cree un archivo denominado UpdateModuleTwinDesiredProperties.py en el directorio de trabajo.

Agregue el código siguiente al archivo de Python. Reemplace YourIoTHubConnectionString por la cadena de conexión que copió en Obtención de la cadena de conexión de IoT Hub.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module twin properties before update    :" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

Obtener actualizaciones en el lado de dispositivo

En esta sección, creará una aplicación de Python para obtener la actualización de las propiedades deseadas del módulo gemelo en el dispositivo.

Obtenga la cadena de conexión del módulo. En Azure Portal, vaya a IoT Hub y seleccione Dispositivos en el panel de la izquierda. Seleccione myFirstDevice en la lista de dispositivos y ábralo. En Identidades de módulo, seleccione myFirstModule. Seleccione el icono de copia para la Cadena de conexión (clave principal). Necesita esta cadena de conexión en un paso siguiente.
En el símbolo del sistema, ejecute el siguiente comando para instalar el paquete azure-iot-device:
```
pip install azure-iot-device
```
Con un editor de texto, cree un archivo denominado ReceiveModuleTwinDesiredPropertiesPatch.py en el directorio de trabajo.

Agregue el código siguiente al archivo de Python. Reemplace YourModuleConnectionString por la cadena de conexión de módulo que copió en el paso 1.

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


def main():
    print ("Starting the IoT Hub Python sample...")
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubModuleClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Ejecución de las aplicaciones

En esta sección, ejecuta la aplicación de dispositivo ReceiveModuleTwinDesiredPropertiesPatch y, luego, ejecuta la aplicación de servicio UpdateModuleTwinDesiredProperties para actualizar las propiedades deseadas del módulo.

Abra un símbolo del sistema y ejecute la aplicación de dispositivo:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Abra otro símbolo del sistema y ejecute la aplicación de dispositivo:
```
python UpdateModuleTwinDesiredProperties.py
```
Observe que la propiedad TelemetryInterval deseada aparece en el módulo gemelo actualizado en la salida de la aplicación de servicio:

La misma propiedad aparece en la revisión de propiedades deseada recibida en la salida de la aplicación de dispositivo: