Introducción a las identidades de módulo de IoT Hub y a las identidades de módulo gemelas

Artículo
12/04/2024

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

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.

En este artículo se muestra cómo desarrollar dos tipos de aplicaciones:

Aplicaciones de dispositivo que ven y actualizan las propiedades notificadas de la identidad de módulo gemela y controlan las solicitudes para actualizar las propiedades deseadas.
Aplicaciones de servicio que pueden leer y establecer propiedades deseadas de identidad de módulo.

Nota:

Este artículo está diseñado para complementar los ejemplos del SDK de Azure IoT a los que se hace referencia desde este artículo. Puede usar las herramientas del SDK para compilar aplicaciones de dispositivo y back-end.

Requisitos previos

Un centro de IoT
Un dispositivo del centro de IoT
Una identidad de módulo del dispositivo del centro de IoT
Si la aplicación usa el protocolo MQTT, asegúrese de que el puerto 8883 esté abierto en el firewall. El protocolo MQTT se comunica a través del puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

Requiere Visual Studio

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para .NET para crear código de aplicación de servicio de dispositivo y back-end para identidades de módulo gemelas.

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para:

Recuperación de una identidad de módulo gemela y examen de las propiedades notificadas
Actualización las propiedades notificadas de la identidad de módulo gemela
Creación de un controlador de devolución de llamada de actualización de propiedades deseadas del módulo

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.

Paquete NuGet de dispositivo necesario

Las aplicaciones cliente de dispositivo escritas en C# requieren el paquete NuGet Microsoft.Azure.Devices.Client.

Agregue estas instrucciones using para usar la biblioteca de dispositivos.

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

Conectarse a un dispositivo

La clase ModuleClient expone todos los métodos necesarios para interactuar con la identidad de módulo gemela desde el dispositivo.

Conéctese al dispositivo mediante el método CreateFromConnectionString con la cadena de conexión de identidad de módulo.

Llamar a CreateFromConnectionString sin un parámetro de transporte se conecta mediante el transporte AMQP predeterminado.

En este ejemplo se conecta al dispositivo mediante el transporte AMQP predeterminado.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Recuperación de una identidad de módulo gemela y examen de las propiedades

Llame a GetTwinAsync para recuperar las propiedades de la identidad de módulo gemela actual en un objeto Gemelo.

Este ejemplo recupera y muestra las propiedades de la identidad de módulo gemela en formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Actualización de las propiedades notificadas de la identidad de módulo gemela

Para actualizar una propiedad notificada de gemelo:

Crear un objeto de TwinCollection para la actualización de la propiedad notificada
Actualizar una o varias propiedades notificadas dentro del objeto TwinCollection
Use UpdateReportedPropertiesAsync para insertar los cambios de propiedad notificados en el servicio IoT Hub

Por ejemplo:

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Creación de un controlador de devolución de llamada de actualización de propiedades deseada

Pase el nombre del método del controlador de devolución de llamada a SetDesiredPropertyUpdateCallbackAsync para crear un controlador de devolución de llamada de actualización de propiedad deseada que se ejecute cuando se cambie una propiedad deseada en el la identidad de módulo gemela.

Por ejemplo, esta llamada configura el sistema para que notifique a un método llamado OnDesiredPropertyChangedAsync cada vez que se modifique una propiedad deseada del módulo.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Las propiedades de la identidad de módulo gemela se pasan al método de devolución de llamada como TwinCollection y se pueden examinar como estructuras KeyValuePair.

En este ejemplo se reciben las actualizaciones de propiedades deseadas como TwinCollection y, a continuación, recorre e imprime las actualizaciones de la colección KeyValuePair. Después de recorrer en bucle la colección KeyValuePair, el código llama a UpdateReportedPropertiesAsync para actualizar la propiedad notificada DateTimeLastDesiredPropertyChangeReceived para mantener actualizada la última hora actualizada.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Ejemplo de módulo SDK

El SDK de Azure IoT para .NET proporciona ejemplos de funcionamiento de aplicaciones de dispositivos que administran tareas de la identidad de módulo gemela. Para más información, vea:

Creación de una aplicación back-end

Esta sección describe cómo leer y actualizar los campos de identidad de módulo.

La clase RegistryManager expone todos los métodos necesarios para crear una aplicación back-end que interactúe con las identidades de módulo gemelas desde el servicio.

Paquete NuGet de servicio requerido

Las aplicaciones de servicio back-end requieren el paquete NuGet de Microsoft.Azure.Devices.

Agregue estas instrucciones using para usar la biblioteca de servicios.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Conexión a IoT Hub

Puede conectar un servicio back-end a IoT Hub mediante los siguientes métodos:

Directiva de acceso compartido
Microsoft Entra

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.

Conexión mediante una directiva de acceso compartido

Conecte una aplicación back-end a un centro de IoT mediante CreateFromConnectionString.

El método UpdateModuleAsync usado en esta sección requiere el permiso de la directiva de acceso compartido de Service Connect para agregar las propiedades deseadas a un módulo. Como parámetro de CreateFromConnectionString, proporcione una cadena de conexión de directiva de acceso compartido que incluya el permiso de Service Connect. Para obtener más información sobre las directivas de acceso compartido, consulte Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Conexión mediante Microsoft Entra

Una aplicación back-end que usa Microsoft Entra debe autenticarse con éxito y obtener una credencial de token de seguridad antes de conectarse a IoT Hub. Este token se pasa a un método de conexión de IoT Hub. Para obtener información general sobre cómo configurar y usar Microsoft Entra para IoT Hub, consulte Controlar el acceso a IoT Hub mediante Microsoft Entra ID.

Configuración de la aplicación de Microsoft Entra

Debe configurar una aplicación de Microsoft Entra que esté configurada para la credencial de autenticación preferida. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son:

Secreto del cliente
Certificado
Credencial de identidad federada

Las aplicaciones de Microsoft Entra pueden requerir permisos de rol específicos dependiendo de las operaciones que se realicen. Por ejemplo, Colaborador de gemelos de IoT Hub es necesario para permitir el acceso de lectura y escritura a un dispositivo IoT Hub y a los módulos gemelos. Para obtener más información, consulte Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para obtener más información sobre la configuración de una aplicación Microsoft Entra, consulte Inicio rápido: Registrar una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación back-end es usar DefaultAzureCredential, ero se recomienda usar un método diferente en un entorno de producción, incluyendo un TokenCredential o ChainedTokenCredential específico. Para simplificar, esta sección describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para obtener más información sobre las ventajas y las desventajas de usar DefaultAzureCredential, consulte Guía de uso de DefaultAzureCredential.

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se esté ejecutando. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra requiere estos paquetes NuGet y las instrucciones using correspondientes:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

En este ejemplo, el secreto de cliente de registro de la aplicación Microsoft Entra, el id. de cliente y el id. de inquilino se agregan a las variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación exitosa de Microsoft Entra es una credencial de token de seguridad que se pasa a un método de conexión de IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

El TokenCredential resultante puede entonces ser pasado a un método de conexión a IoT Hub para cualquier cliente del SDK que acepte credenciales de Microsoft Entra:

En este ejemplo, el TokenCredential se pasa a ServiceClient.Create para crear un objeto de conexión ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

En este ejemplo, el TokenCredential se pasa a RegistryManager.Create para crear un objeto RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Código de ejemplo

Para ver un ejemplo práctico de autenticación de servicios de Microsoft Entra, consulte Ejemplo de autenticación basada en roles.

Lectura y actualización de los campos de identidad del módulo

Llame a GetModuleAsync para recuperar los campos de la identidad de módulo gemela actual en un objeto Módulo.

La clase Module incluye properties que corresponden a secciones de una identidad de módulo gemela. Use las propiedades de la clase Módulo para ver y actualizar los campos de la identidad de módulo gemela. Puede usar las propiedades del objeto Module para actualizar varios campos antes de escribir las actualizaciones en el dispositivo mediante UpdateModuleAsync.

Después de actualizar los campos de la identidad de módulo gemela, llame a UpdateModuleAsync para escribir las actualizaciones de los campos de objeto Module en un dispositivo. Use la lógica try y catch junto con un controlador de errores para detectar errores de revisión con formato incorrecto de UpdateModuleAsync.

Este ejemplo recupera un módulo en un objeto Module, actualiza la propiedad LastActivityTime de module y luego actualiza el módulo en IoT Hub mediante UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

API de otros módulos

GetModulesOnDeviceAsync: recupera las identidades de módulo en un dispositivo
RemoveModuleAsync: elimina un módulo registrado anteriormente de un dispositivo

Ejemplo del servicio SDK

El SDK de Azure IoT para .NET proporciona una muestra de trabajo de una aplicación de servicio que administra tareas de la identidad de módulo gemela. Para obtener más información, consulte Pruebas E2E del Administrador de registros.

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.

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para Python para crear código de aplicación de servicio de dispositivo y back-end para identidades de módulo gemelas.

Instalar paquetes

La biblioteca azure-iot-device debe estar instalada para crear aplicaciones de dispositivos.

pip install azure-iot-device

La biblioteca azure-iot-hub debe estar instalada para crear aplicaciones de servicios back-end.

pip install azure-iot-hub

La biblioteca msrest se usa para capturar excepciones HTTPOperationError.

pip install msrest

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el código de aplicación de dispositivo para:

Recuperación de una identidad de módulo gemela y examen de las propiedades notificadas
Actualización de las propiedades notificadas de la identidad de módulo gemela
Creación de un controlador de devolución de llamada de actualización de propiedades deseadas de la identidad de módulo gemela

Importante

Instrucciones import

Agregue esta instrucción import para usar la biblioteca de dispositivos.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Conectarse a un dispositivo

La clase IoTHubModuleClient contiene métodos que se pueden usar para trabajar con identidades de módulo gemelas.

Para conectar una aplicación a un dispositivo:

Llame a create_from_connection_string para agregar la cadena de conexión de identidad del módulo
Llame a conectar para conectar el cliente del dispositivo a una instancia de Azure IoT Hub

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Recuperación de una identidad de módulo gemela y examen de las propiedades

Llame a get_twin para recuperar la identidad de módulo gemela del servicio Azure IoT Hub. La información del gemelo se coloca en una variable que se puede examinar.

En este ejemplo se recupera el dispositivo gemelo y se usa el comando print para ver el dispositivo gemelo en formato JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Actualización de las propiedades notificadas de la identidad de módulo gemela

Puede aplicar una revisión para actualizar las propiedades notificadas de la identidad de módulo gemela o en formato JSON.

Para aplicar una revisión para actualizar las propiedades notificadas:

Asigne una revisión JSON de propiedad notificada a una variable.
Llame a patch_twin_reported_properties para aplicar la revisión JSON a las propiedades notificadas.

Por ejemplo:

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Creación de un controlador de devolución de llamada de actualización de propiedades deseadas de la identidad de módulo gemela

Llame a on_twin_desired_properties_patch_received para crear una función de controlador o corrutina a la que se llama cuando se recibe una revisión de propiedades deseadas de la identidad de módulo gemela. El controlador toma un argumento, que es la revisión gemela en forma de un objeto de diccionario JSON.

En este ejemplo se configura un controlador de revisiones de propiedades deseado denominado twin_patch_handler.

Por ejemplo:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

El twin_patch_handler recibe e imprime las actualizaciones de propiedades deseadas de JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para Python proporciona un ejemplo de funcionamiento de aplicaciones de dispositivos que administran tareas de la identidad de módulo gemela:

get_twin: conéctese a un dispositivo y recupere información de gemelos.
update_twin_reported_properties: actualice las propiedades notificadas del gemelo.
receive_twin_desired_properties: reciba y actualice las propiedades deseadas.

Creación de una aplicación back-end

En esta sección se describe cómo crear una aplicación de back-end para recuperar y actualizar las propiedades deseadas de la identidad de módulo gemela.

La clase IoTHubRegistryManager expone todos los métodos necesarios para crear una aplicación back-end que interactúe con la identidad de módulo gemela desde el servicio.

Instrucciones de importación de servicio

Agregue esta instrucción import para usar la biblioteca de servicio.

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

Conexión al centro de IoT

Puede conectar un servicio back-end a IoT Hub mediante los siguientes métodos:

Directiva de acceso compartido
Microsoft Entra

Importante

Conexión mediante una directiva de acceso compartido

Conéctese a IoT Hub mediante from_connection_string.

El método update_module_twin usado en esta sección requiere el permiso de la directiva de acceso compartido de Service Connect para agregar las propiedades deseadas a un módulo. Como parámetro de from_connection_string, proporcione una cadena de conexión de directiva de acceso compartido que incluya el permiso de Service Connect. Para obtener más información sobre las directivas de acceso compartido, consulte Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Conexión mediante Microsoft Entra

Para obtener una información general de la autenticación del SDK de Python, consulte Autenticar aplicaciones de Python en servicios Azure usando el SDK de Azure para Python

Configuración de la aplicación de Microsoft Entra

Secreto del cliente
Certificado
Credencial de identidad federada

Para obtener más información sobre la configuración de una aplicación Microsoft Entra, consulte Inicio rápido: Registrar una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación back-end es usar DefaultAzureCredential, ero se recomienda usar un método diferente en un entorno de producción, incluyendo un TokenCredential o ChainedTokenCredential específico. Para simplificar, esta sección describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para obtener más información sobre las ventajas y desventajas de usar DefaultAzureCredential, consulte Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para Python.

DefaultAzureCredential admite distintos mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se esté ejecutando. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra requiere este paquete de importación y la instrucción import correspondiente:

pip install azure-identity

from azure.identity import DefaultAzureCredential

En este ejemplo, el secreto de cliente de registro de la aplicación Microsoft Entra, el id. de cliente y el id. de inquilino se han agregado a las variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación exitosa de Microsoft Entra es una credencial de token de seguridad que se pasa a un método de conexión de IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

El AccessToken resultante puede entonces pasarse a from_token_credential para conectarse a IoT Hub para cualquier cliente SDK que acepte credenciales Microsoft Entra:

IoTHubRegistryManager para crear una conexión de servicio a IoT Hub mediante una credencial de token Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential requiere dos parámetros:

La dirección URL del servicio Azure: la dirección URL del servicio Azure debe tener el formato {Your Entra domain URL}.azure-devices.net sin un prefijo https://. Por ejemplo, MyAzureDomain.azure-devices.net.
El token de credenciales de Azure

En este ejemplo, la credencial de Azure se obtiene mediante DefaultAzureCredential. A continuación, la dirección URL y las credenciales del servicio de Azure se proporcionan a IoTHubRegistryManager.from_token_credential para crear la conexión a IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Ejemplos de código

Para obtener ejemplos de trabajo de autenticación del servicio Microsoft Entra, consulte Biblioteca de autenticación de Microsoft (MSAL) para Python.

Recuperación y actualización de las propiedades deseadas de la identidad de módulo gemela

Puede actualizar las propiedades deseadas desde una aplicación back-end mediante update_module_twin.

Para recuperar y actualizar las propiedades deseadas de la identidad de módulo gemela:

Llame a get_module_twin para obtener la versión actual de la identidad de módulo gemela.
Use la clase Gemelo para agregar propiedades deseadas en formato JSON.
Llame a update_module_twin para aplicar la revisión al dispositivo gemelo. También puede usar replace_module_twin para reemplazar las propiedades y etiquetas deseadas para una identidad de módulo gemela.

En este ejemplo se actualiza la propiedad deseada telemetryInterval a 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity 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 identity 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" )

Ejemplo del servicio SDK

El SDK de Azure IoT para Python proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas de la identidad de módulo gemelo de dispositivo. Para obtener más información, consulte Probar el Administrador de registros de IoTHub.

Requiere Node.js versión 10.0.x o posterior

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para Node.js para crear código de aplicación de servicio de dispositivo y back-end para identidades de módulo gemelas.

Creación de una aplicación de dispositivo

En esta sección se describe cómo usar el paquete de azure-iot-device en el SDK de Azure IoT para Node.js para crear una aplicación de dispositivo para:

Recuperación de una identidad de módulo gemela y examen de las propiedades notificadas
Actualización las propiedades notificadas de la identidad de módulo gemela
Recepción del aviso de los cambios en la propiedad deseada de la identidad de módulo gemela

Importante

Instalación de paquetes de SDK

Ejecute este comando para instalar el SDK de dispositivo de azure-iot-device en la máquina de desarrollo:

npm install azure-iot-device --save

El paquete azure-iot-device contiene objetos que interactúan con dispositivos IoT. La clase Gemelo incluye objetos específicos de gemelos. En esta sección describe el código de clase Client que se usa para leer y escribir datos de la identidad de módulo gemela del dispositivo.

Selección de un protocolo de transporte

EClientl objeto admite estos protocolos:

Amqp
Http: al usar Http, la instancia de Client comprueba si hay mensajes de IoT Hub con poca frecuencia (cada 25 minutos como mínimo).
Mqtt
MqttWs
AmqpWs

Instale los protocolos de transporte necesarios en la máquina de desarrollo.

Por ejemplo, este comando instala el protocolo Amqp:

npm install azure-iot-device-amqp --save

Para obtener más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTPS, consulte Guía de comunicaciones de nube a dispositivo y Elegir un protocolo de comunicación de dispositivos.

Creación de un objeto de cliente

Cree un objeto Client mediante el paquete instalado.

Por ejemplo:

const Client = require('azure-iot-device').Client;

Creación de un objeto de protocolo

Cree un objeto Protocol mediante un paquete de transporte instalado.

En este ejemplo se asigna el protocolo AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Adición de la cadena de conexión del dispositivo y el protocolo de transporte

Llame a fromConnectionString para proporcionar parámetros de conexión de dispositivo:

connStr: cadena de conexión del módulo de identidad del centro de IoT.
transportCtor: el protocolo de transporte.

En este ejemplo se usa el protocolo de transporte Amqp:

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Apertura de la conexión a IoT Hub

Use el método open para abrir una conexión entre un dispositivo IoT e IoT Hub.

Por ejemplo:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Recuperación de una identidad de módulo gemela y examen de las propiedades notificadas

Llame a getTwin para recuperar la información actual de la identidad de módulo gemela en un objeto Gemelo.

A continuación, el código de dispositivo puede acceder a las propiedades de la identidad de módulo gemela.

Por ejemplo:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Actualización de las propiedades notificadas de la identidad de módulo gemela

Use actualizar para actualizar las propiedades notificadas del dispositivo. Incluya una revisión con formato JSON como el primer parámetro y el método de devolución de llamada de estado de ejecución de la función como segundo parámetro para el método.

En este ejemplo, se almacena una revisión de la identidad de módulo gemela con formato JSON en la variable patch. La revisión contiene un valor de actualización de la identidad de módulo gemela connectivity de cellular. El controlador de revisiones y errores se pasan al método update. Si se produce un error, se muestra un mensaje de error de consola.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Recepción del aviso de los cambios en la propiedad deseada de la identidad de módulo gemela

Cree un agente de escucha de eventos de actualización de propiedades deseada de identidad de módulo gemela que se ejecute cuando se cambie una propiedad deseada pasando el nombre del método del controlador de devolución de llamada a twin.on.

El agente de escucha de eventos de propiedad deseada puede adoptar las siguientes formas:

Recepción de todas las revisiones con un único controlador de eventos
Recepción de un evento si algo cambia en una agrupación de propiedades
Recepción de un evento para un único cambio de propiedad

Recepción de todas las revisiones con un único controlador de eventos

Puede crear un agente de escucha para recibir cualquier cambio de propiedad deseado.

Este código de ejemplo genera las propiedades que se reciben del servicio.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Recepción de un evento si algo cambia en una agrupación de propiedades

Puede crear un agente de escucha para recibir un evento si algo en una agrupación de propiedades cambia.

Por ejemplo:

Las propiedades minTemperature y maxTemperature se encuentran en una agrupación de propiedades denominada properties.desired.climate changes.
Una aplicación de servicio back-end aplica esta revisión para actualizar las propiedades deseadas minTemperature y maxTemperature:
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```

Este código configura un agente de escucha de eventos de cambio de propiedad deseado que se desencadena para los cambios dentro de la agrupación de propiedades de properties.desired.climate. Si hay un cambio de propiedad deseado en este grupo, los mensajes de cambio de temperatura mínimo y máximo que se muestran en la consola:

twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

Recepción de un evento para un único cambio de propiedad

Puede configurar un agente de escucha para un único cambio de propiedad. En este ejemplo, el código de este evento solo se ejecuta si el valor booleano fanOn forma parte de la revisión. El código genera el nuevo estado deseado fanOn cada vez que el servicio lo actualiza.

Una aplicación back-end aplica esta revisión de propiedad deseada:

 const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

El agente de escucha solo se desencadena cuando cambia la propiedad fanOn:

 twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

Ejemplo completo

Este ejemplo encapsula los principios de esta sección, incluyendo el anidamiento de función de devolución de llamada multinivel.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Ejemplos de SDK de dispositivos

El SDK de Azure IoT para Node.js proporciona ejemplos de funcionamiento de aplicaciones de dispositivos que administran tareas de identidad de módulo gemela. Para más información, vea:

Creación de una aplicación back-end

En esta sección se describe cómo crear una aplicación back-end que recupere una identidad de módulo gemela y actualice las propiedades deseadas.

Instalación del paquete de SDK de servicio

Ejecute este comando para instalar azure-iothub en la máquina de desarrollo:

npm install azure-iothub --save

Creación de un objeto de registro

La clase Registro expone todos los métodos necesarios para interactuar con las identidades de módulo gemelas desde una aplicación back-end.

let Registry = require('azure-iothub').Registry;

Conexión al centro de IoT

Puede conectar un servicio back-end a IoT Hub mediante los siguientes métodos:

Directiva de acceso compartido
Microsoft Entra

Importante

Conexión mediante una directiva de acceso compartido

Use fromConnectionString para conectarse a IoT Hub.

El método update usado en esta sección requiere el permiso de la directiva de acceso compartido de Service Connect para agregar las propiedades deseadas a un módulo. Como parámetro de fromConnectionString, proporcione una cadena de conexión de directiva de acceso compartido que incluya el permiso de Service Connect. Para obtener más información sobre las directivas de acceso compartido, consulte Control del acceso a IoT Hub con firmas de acceso compartido.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Conexión mediante Microsoft Entra

Para obtener información general sobre la autenticación del SDK de Node.js, consulte:

Configuración de la aplicación de Microsoft Entra

Secreto del cliente
Certificado
Credencial de identidad federada

Para obtener más información sobre la configuración de una aplicación Microsoft Entra, consulte Inicio rápido: Registrar una aplicación con la plataforma de identidad de Microsoft.

Autenticación con DefaultAzureCredential

La forma más sencilla de usar Microsoft Entra para autenticar una aplicación back-end es usar DefaultAzureCredential, ero se recomienda usar un método diferente en un entorno de producción, incluyendo un TokenCredential o ChainedTokenCredential específico. Para simplificar, esta sección describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para obtener más información sobre las ventajas y desventajas de usar DefaultAzureCredential, consulte Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para JavaScript

Microsoft Entra requiere este paquete:

npm install --save @azure/identity

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

A continuación, se puede pasar el token de credencial resultante a fromTokenCredential para conectarse a IoT Hub para cualquier cliente SDK que acepte las credenciales de Microsoft Entra:

fromTokenCredential requiere dos parámetros:

La dirección URL del servicio Azure: la dirección URL del servicio Azure debe tener el formato {Your Entra domain URL}.azure-devices.net sin un prefijo https://. Por ejemplo, MyAzureDomain.azure-devices.net.
El token de credenciales de Azure

En este ejemplo, la credencial de Azure se obtiene mediante DefaultAzureCredential. A continuación, la dirección URL y las credenciales del dominio de Azure se proporcionan a Registry.fromTokenCredential para crear la conexión a IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Ejemplos de código

Para obtener ejemplos de trabajo de autenticación del servicio Microsoft Entra, consulte Ejemplos de identidad de Azure.

Recuperación de una identidad de módulo gemela y actualización de las propiedades deseadas

Puede crear una revisión que contenga las actualizaciones de propiedades deseadas para una identidad de módulo gemela.

Para actualizar una identidad de módulo gemela:

Llame a getModuleTwin para recuperar el dispositivo objeto Gemelo.
Formatee una revisión que contenga la actualización de la identidad de módulo gemela. La revisión tiene el formato JSON tal como se describe en la clase Gemelo. Una revisión del servicio back-end contiene actualizaciones de propiedades deseadas. Para obtener más información sobre el formato de revisión, consulte Formato de etiquetas y propiedades.
Llame a actualizar para actualizar la identidad del módulo gemela con la revisión.

En este ejemplo, se recupera la identidad de módulo gemela para myDeviceId y myModuleId. A continuación, se aplica un parche a los gemelos que contienen información climate.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Ejemplos del SDK de servicio

El SDK de Azure IoT para Node.js proporciona ejemplos de funcionamiento de aplicaciones de servicio que administran tareas de identidad de módulo gemela. Para más información, vea:

Compartir vía

Introducción a las identidades de módulo de IoT Hub y a las identidades de módulo gemelas

Requisitos previos

Información general

Creación de una aplicación de dispositivo

Paquete NuGet de dispositivo necesario

Conectarse a un dispositivo

Recuperación de una identidad de módulo gemela y examen de las propiedades

Actualización de las propiedades notificadas de la identidad de módulo gemela

Creación de un controlador de devolución de llamada de actualización de propiedades deseada

Ejemplo de módulo SDK

Creación de una aplicación back-end

Paquete NuGet de servicio requerido

Conexión a IoT Hub

Conexión mediante una directiva de acceso compartido

Conexión mediante Microsoft Entra

Configuración de la aplicación de Microsoft Entra

Autenticación con DefaultAzureCredential

Código de ejemplo

Lectura y actualización de los campos de identidad del módulo

API de otros módulos

Ejemplo del servicio SDK

Información general

Instalar paquetes

Creación de una aplicación de dispositivo

Instrucciones import

Conectarse a un dispositivo

Recuperación de una identidad de módulo gemela y examen de las propiedades

Actualización de las propiedades notificadas de la identidad de módulo gemela

Creación de un controlador de devolución de llamada de actualización de propiedades deseadas de la identidad de módulo gemela

Ejemplos de dispositivos del SDK

Creación de una aplicación back-end

Instrucciones de importación de servicio

Conexión al centro de IoT

Conexión mediante una directiva de acceso compartido

Conexión mediante Microsoft Entra

Configuración de la aplicación de Microsoft Entra

Autenticación con DefaultAzureCredential

Ejemplos de código

Recuperación y actualización de las propiedades deseadas de la identidad de módulo gemela

Ejemplo del servicio SDK

Información general

Creación de una aplicación de dispositivo

Instalación de paquetes de SDK

Selección de un protocolo de transporte

Creación de un objeto de cliente

Creación de un objeto de protocolo

Adición de la cadena de conexión del dispositivo y el protocolo de transporte

Apertura de la conexión a IoT Hub

Recuperación de una identidad de módulo gemela y examen de las propiedades notificadas

Actualización de las propiedades notificadas de la identidad de módulo gemela

Recepción del aviso de los cambios en la propiedad deseada de la identidad de módulo gemela

Recepción de todas las revisiones con un único controlador de eventos

Recepción de un evento si algo cambia en una agrupación de propiedades

Recepción de un evento para un único cambio de propiedad

Ejemplo completo

Ejemplos de SDK de dispositivos

Creación de una aplicación back-end

Instalación del paquete de SDK de servicio

Creación de un objeto de registro

Conexión al centro de IoT

Conexión mediante una directiva de acceso compartido

Conexión mediante Microsoft Entra

Configuración de la aplicación de Microsoft Entra

Autenticación con DefaultAzureCredential

Ejemplos de código

Recuperación de una identidad de módulo gemela y actualización de las propiedades deseadas

Ejemplos del SDK de servicio

Comentarios

Recursos adicionales