Introducción a los dispositivos gemelos

Artículo
12/04/2024

Use el SDK de dispositivo y el SDK de servicio de Azure IoT Hub para desarrollar aplicaciones que controle tareas comunes de dispositivos gemelos. Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. IoT Hub conserva un dispositivo gemelo por cada dispositivo que se conecta a él.

Puede usar dispositivos gemelos para:

Almacenar metadatos del dispositivo desde el back-end de la solución
Notificar la información sobre el estado actual, como las funcionalidades y las condiciones disponibles (por ejemplo, el método de conectividad usado) de la aplicación del dispositivo
Sincronizar el estado de flujos de trabajo de larga duración (como las actualizaciones del firmware y de la configuración) entre la aplicación del dispositivo y la del back-end
Consultar los metadatos, la configuración o el estado del dispositivo

Para obtener más información sobre los dispositivos gemelos, incluido cuándo usar dispositivos gemelos, consulte Descripción y uso de dispositivos gemelos en 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:

Las aplicaciones de dispositivo pueden controlar las solicitudes para actualizar las propiedades deseadas y responder con cambios en las propiedades notificadas.
Las aplicaciones de servicio pueden actualizar etiquetas de dispositivo gemelo, establecer nuevas propiedades deseadas y consultar dispositivos basados en valores de dispositivo gemelo.

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

Una instancia de IoT Hub. Algunas llamadas al SDK requieren la cadena de conexión principal de IoT Hub, así que anótela.
Un dispositivo registrado. Algunas llamadas al SDK requieren la cadena de conexión principal del dispositivo, así que anótela.
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).
Requisitos del SDK de lenguaje:
- SDK de .NET : requiere Visual Studio.
- Python SDK - Se recomienda usar la versión de Python 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.
- Java: requiere el Java SE Development Kit. Asegúrese de seleccionar Java 8 en Soporte técnico a largo plazo para obtener descargas de JDK 8.
- Node.js: 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 .NET para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

Las aplicaciones de dispositivo pueden leer y escribir propiedades notificadas de gemelos y recibir notificaciones de los cambios de propiedad de gemelos deseados establecidos por una aplicación de back-end o IoT Hub.

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

Recuperar un dispositivo gemelo y examinar las propiedades notificadas
Actualización de las propiedades notificadas de dispositivos gemelos
Creación de un controlador de devolución de llamada de actualización de propiedades deseada

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.

Agregar paquete NuGet de dispositivo

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

Conectarse a un dispositivo

La clase DeviceClient expone todos los métodos necesarios para interactuar con dispositivos gemelos desde el dispositivo.

Conéctese al dispositivo mediante el método CreateFromConnectionString junto con la cadena de conexión del dispositivo y el protocolo de transporte de conexión.

El parámetro de protocolo de transporte CreateFromConnectionString TransportType admite los siguientes protocolos de transporte:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only

El protocolo Http1 no se admite para las actualizaciones de dispositivos gemelos.

Este ejemplo se conecta a un dispositivo mediante el protocolo de transporte Mqtt.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Recuperación de un dispositivo gemelo y examen de propiedades

Llame a GetTwinAsync para recuperar las propiedades del dispositivo gemelo actual. Hay muchas propiedades del objeto Gemelo que puede utilizar para acceder a áreas específicas de los JSON Twin incluyendo Properties, Status, Tags, y Version.

En este ejemplo se recuperan las propiedades del dispositivo gemelo y se imprimen los valores del gemelo en formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Actualización de las propiedades notificadas de dispositivos gemelos

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 _deviceClient.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

Cree un controlador de devolución de llamada de actualización de propiedad deseada que se ejecute cuando se cambia una propiedad deseada en el dispositivo gemelo pasando el nombre del método del controlador de devolución de llamada a SetDesiredPropertyUpdateCallbackAsync.

Por ejemplo, esta llamada configura el sistema para notificar a un método denominadoOnDesiredPropertyChangedAsync cada vez que se cambia una propiedad deseada.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Las propiedades del gemelo 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 _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Ejemplo de dispositivo del SDK

El SDK de Azure IoT para .NET proporciona un ejemplo de trabajo de una aplicación de dispositivo que controla las tareas del dispositivo gemelo. Para obtener más información, consulte TwinSample.

Creación de una aplicación back-end

Una aplicación back-end se conecta a un dispositivo a través de IoT Hub y puede leer las propiedades notificadas y deseadas del dispositivo, escribir propiedades deseadas del dispositivo y ejecutar consultas de dispositivo.

En esta sección se describe cómo crear código de aplicación back-end para:

Leer y actualizar campos de dispositivos gemelos
Creación de una consulta de dispositivo gemelo

La clase RegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.

Agregar paquete NuGet de servicio

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

Conexión al centro de IoT

Puede conectar un servicio de 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 dispositivo mediante CreateFromConnectionString. La aplicación necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crear una en caso de que no exista. Proporcione esta cadena de conexión de directiva de acceso compartido como parámetro para fromConnectionString. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Conexión mediante Microsoft Entra

Una aplicación de back-end que usa Microsoft Entra debe autenticarse de forma correcta 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, vea Control del 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 que prefiera. La aplicación contiene parámetros como el secreto de cliente que son usados por la aplicación de back-end para autenticarse. Las configuraciones de autenticación de aplicaciones disponibles son las siguientes:

Secreto del cliente
Certificado
Credencial de identidad federada

Es posible que las aplicaciones de Microsoft Entra necesiten permisos de rol específicos en función 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 más información, vea Administración del acceso a IoT Hub mediante la asignación de roles de RBAC de Azure.

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de 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 de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia de TokenCredential o reducida de ChainedTokenCredential específica. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para información sobre las ventajas y las desventajas de usar DefaultAzureCredential, vea 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 ejecute. Intenta usar varios tipos de credenciales en un orden hasta que encuentra una credencial que funciona.

Microsoft Entra necesita 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 de Microsoft Entra, el id. de cliente y el id. de inquilino se agregan a variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación correcta 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 valor TokenCredential resultante se puede pasar a un método de conexión a IoT Hub para cualquier cliente del SDK que acepte credenciales de Microsoft Entra:

En este ejemplo, 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, 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 obtener un ejemplo práctico de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.

Leer y actualizar campos de dispositivos gemelos

Puede recuperar los campos gemelos actuales en un objeto Gemelo mediante una llamada a GetTwinAsync.

La clase Twin incluye propiedades que corresponden a cada sección de un dispositivo gemelo. Use las propiedades de la clase Twin para ver y actualizar campos gemelos del dispositivo. Puede usar las propiedades del objeto Twin para actualizar varios campos gemelos antes de escribir las actualizaciones en el dispositivo mediante UpdateTwinAsync.

Después de realizar actualizaciones de campos gemelos, llame a UpdateTwinAsync para escribir actualizaciones de campo de objeto Twin 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 UpdateTwinAsync.

Leer y actualizar etiquetas de dispositivo gemelo

Utilice la propiedad del dispositivo gemelo Etiquetas para leer y escribir la información de las etiquetas del dispositivo.

Actualización de etiquetas mediante un objeto gemelo

En este ejemplo se crea una revisión de etiqueta location , se le asigna al objeto Twin mediante la propiedad Tags y, a continuación, se aplica la revisión mediante UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

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

Actualización de etiquetas mediante una cadena JSON

Puede crear y aplicar una revisión de actualización de información de dispositivos gemelos con formato JSON. IoT Hub analiza y aplica la revisión si tiene el formato correcto.

En este ejemplo se llama a GetTwinAsync para recuperar los campos gemelos actuales en un objeto Twin, crea una revisión con formato JSON tag con información de región y ubicación de la planta y, a continuación, llama a UpdateTwinAsync para aplicar la revisión para actualizar el dispositivo gemelo. Se muestra un mensaje de error si UpdateTwinAsync falla.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Visualización y actualización de las propiedades deseadas del gemelo

Use la propiedad del objeto gemelo TwinProperties.Desired para leer y escribir información de propiedad deseada del dispositivo. Actualice las propiedades del gemelo Desired mediante una revisión con formato JSON.

Este ejemplo llama a GetTwinAsync para recuperar los campos gemelos actuales del dispositivo en un objeto Twin, actualiza la propiedad deseada del gemelo speed, y luego llama a UpdateTwinAsync para aplicar el objeto Twin para actualizar el gemelo del dispositivo.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Otros métodos de actualización de gemelos

También puede aplicar actualizaciones de gemelos mediante estos métodos del SDK:

Llame a ReplaceTwinAsync para reemplazar todo el dispositivo gemelo.
Llame a UpdateTwins2Async para actualizar una lista de gemelos creados anteriormente en el sistema.

Creación de una consulta de dispositivo gemelo

En esta sección se muestran dos consultas de dispositivo gemelo. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

Para crear una consulta de dispositivo gemelo, llame a CreateQuery para enviar una consulta SQL de gemelos y obtener una interfaz IQuery. Opcionalmente, puede llamar a CreateQuery con un segundo parámetro para especificar un número máximo de elementos por página.

A continuación, llame al método GetNextAsTwinAsync o GetNextAsJsonAsync tantas veces como sea necesario para recuperar todos los resultados del gemelo.

GetNextAsTwinAsync para recuperar el siguiente resultado paginado como objetos Gemelo.
GetNextAsJsonAsync para recuperar el siguiente resultado paginado como cadenas JSON.

La interfaz IQuery incluye una propiedad HasMoreResults booleana que se puede utilizar para comprobar si hay más resultados gemelos que recuperar.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta de Redmond43.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Ejemplo del servicio SDK

El SDK de Azure IoT para .NET proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte Ejemplo del Administrador de registros.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Java para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

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

Recuperación y visualización de un dispositivo gemelo
Actualización de las propiedades notificadas de dispositivos gemelos
Suscripción a los cambios de propiedad deseados

La clase DeviceClient expone todos los métodos necesarios para interactuar con dispositivos gemelos desde el dispositivo.

Importante

Instrucciones de importación de dispositivos

Use las siguientes instrucciones de importación de dispositivos para acceder al SDK de Azure IoT para Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Conexión del dispositivo

Cómo conectarlo a un dispositivo:

Use IotHubClientProtocol para elegir un protocolo de transporte. Por ejemplo:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

Use el constructor DeviceClient para agregar la cadena de conexión principal y el protocolo del dispositivo.

String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Use abrir para conectar el dispositivo a IoT Hub. Si el cliente ya está abierto, el método no hace nada.
```
client.open(true);
```

Recuperación y visualización de un dispositivo gemelo

Después de abrir la conexión de cliente, llame a getTwin para recuperar las propiedades del gemelo actual en un objeto Twin.

Por ejemplo:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Actualización de las propiedades notificadas del dispositivo gemelo

Después de recuperar el gemelo actual, puede empezar a realizar actualizaciones de propiedades notificadas. También puede realizar actualizaciones de propiedades notificadas sin obtener el gemelo actual siempre que tenga la versión de propiedades notificadas correcta. Si envía propiedades notificadas y recibe un error de "error de condición previa", la versión de las propiedades notificadas no está actualizada. En ese caso, vuelva a llamar a getTwin la versión más reciente.

Para actualizar las propiedades notificadas:

Llame a getReportedProperties para capturar las propiedades notificadas del gemelo en un objeto TwinCollection.
Use put para actualizar una propiedad notificada dentro del objeto TwinCollection. Llame a put para cada actualización de propiedad notificada.
Use updateReportedProperties para aplicar el grupo de propiedades notificadas que se actualizaron mediante el método put.

Por ejemplo:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Llame a subscribeToDesiredProperties para suscribirse a los cambios de propiedad deseados. Este cliente recibe una devolución de llamada con un objeto Twin cada vez que se actualiza una propiedad deseada. Esa devolución de llamada contiene las propiedades deseadas completas establecidas o solo la propiedad deseada actualizada en función de cómo se cambió la propiedad deseada.

En este ejemplo se suscribe a los cambios de propiedad deseados. Los cambios de propiedad deseados se pasan a un controlador denominado DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

En este ejemplo, el controlador de devolución de llamada de cambio de propiedad deseada DesiredPropertiesUpdatedHandler llama a getDesiredProperties para recuperar los cambios de propiedad y, a continuación, imprime las propiedades gemelas actualizadas.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Ejemplo de dispositivo del SDK

El SDK de Azure IoT para Java incluye un ejemplo de trabajo para probar los conceptos de la aplicación de dispositivo descritos en este artículo. Para obtener más información, consulte Ejemplo de dispositivo gemelo.

Creación de una aplicación back-end

En esta sección se describe cómo crear una aplicación back-end que:

Actualiza las etiquetas de dispositivo gemelo
Consulta dispositivos mediante filtros en las etiquetas y propiedades

La clase ServiceClient DeviceTwin contiene métodos que los servicios pueden utilizar para acceder a los dispositivos gemelos.

Instrucciones de importación de servicio

Use las siguientes instrucciones de importación de servicio para acceder al SDK de Azure IoT para Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Conexión a IoT Hub

Puede conectar un servicio de 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 un constructor DeviceTwin para crear la conexión con el IoT Hub. El objeto DeviceTwin controla la comunicación con el IoT Hub.

La aplicación necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crear una en caso de que no exista. Proporcione esta cadena de conexión de directiva de acceso compartido como parámetro para fromConnectionString. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

El objeto DeviceTwinDevice representa el dispositivo gemelo con sus propiedades y etiquetas.

Por ejemplo:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Conexión mediante Microsoft Entra

Para obtener información general sobre la autenticación del SDK de Java, vea Autenticación de Azure con Java e Identidad de Azure.

Para simplificar, en esta sección se describe la autenticación mediante un secreto de cliente.

Configuración de la aplicación de Microsoft Entra

Secreto del cliente
Certificado
Credencial de identidad federada

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de 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 de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia de TokenCredential o reducida de ChainedTokenCredential específica. Para más información sobre las ventajas y desventajas de usar DefaultAzureCredential, vea Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para Java.

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

Puede autenticar las credenciales de aplicación de Microsoft Entra mediante DefaultAzureCredentialBuilder. Guarde parámetros de conexión como tenantID del secreto de cliente, clientID y valores de secreto de cliente como variables de entorno. Una vez que se haya creadTokenCredential, páselo a ServiceClient u otro generador como parámetro "credential".

En este ejemplo, DefaultAzureCredentialBuilder intenta autenticar una conexión de la lista descrita en DefaultAzureCredential. El resultado de una autenticación correcta de Microsoft Entra es una credencial de token de seguridad que se pasa a un constructor como ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Autenticación mediante ClientSecretCredentialBuilder

Puede usar ClientSecretCredentialBuilder para crear una credencial mediante la información del secreto de cliente. Si se ejecuta correctamente, este método devuelve un valor TokenCredential que se puede pasar a ServiceClient u otro generador como parámetro "credential".

En este ejemplo, los valores de secreto de cliente de registro de la aplicación de Microsoft Entra, el id. de cliente y el id. de inquilino se han agregado a las variables de entorno. Estas variables de entorno las usa ClientSecretCredentialBuilder para crear la credencial.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Otras clases de autenticación

El SDK de Java también incluye estas clases que autentican una aplicación de back-end con Microsoft Entra:

Ejemplos de código

Para obtener ejemplos prácticos de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.

Actualizar campos gemelos de dispositivo

Para actualizar los campos del dispositivo gemelo:

Use getTwin para recuperar los campos gemelos del dispositivo actual

En este ejemplo se recuperan e imprimen los campos del dispositivo gemelo:

// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

Use un objeto HashSet para add un grupo de pares de etiquetas gemelas
Use setTags para agregar un grupo de pares de etiquetas de un objeto tags a un objeto DeviceTwinDevice

Use updateTwin para actualizar el gemelo en IoT Hub

En este ejemplo se actualizan las etiquetas de dispositivo gemelo de región y planta para un dispositivo gemelo:

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Creación de una consulta de dispositivo gemelo

En esta sección se muestran dos consultas de dispositivo gemelo. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

La clase Query contiene métodos que se pueden usar para crear consultas de estilo SQL en IoT Hub para gemelos, trabajos, trabajos de dispositivo o datos sin procesar.

Para crear una consulta de dispositivo:

Use createSqlQuery para compilar la consulta SQL de gemelos
Use queryTwin para ejecutar la consulta
Use hasNextDeviceTwin para comprobar si hay otro dispositivo gemelo en el conjunto de resultados
Use getNextDeviceTwin para recuperar el siguiente dispositivo gemelo del conjunto de resultados

Las consultas de ejemplo siguientes devuelven un máximo de 100 dispositivos.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta de Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Ejemplo del servicio SDK

El SDK de Azure IoT para Java proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte Ejemplo de dispositivo gemelo.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Python para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

La clase IoTHubDeviceClient contiene métodos que se pueden usar para trabajar con dispositivos gemelos.

En esta sección se describe cómo crear código de aplicación de dispositivo que:

Recupera un dispositivo gemelo y examina las propiedades notificadas
Revisa las propiedades de dispositivos gemelos notificados

Importante

Conectarse a un dispositivo

En esta sección se muestra cómo conectar una aplicación a un dispositivo mediante una clave principal de dispositivo que incluye una clave de acceso compartido.

Para conectar una aplicación a un dispositivo:

Llame a create_from_connection_string para agregar la cadena de conexión del dispositivo.
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 = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

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

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Puede recuperar y examinar la información del dispositivo gemelo, incluidas las etiquetas y las propiedades. La información del dispositivo gemelo recuperada coincide con los datos con formato JSON del dispositivo gemelo que puede ver para un dispositivo en Azure Portal.

Llame a get_twin para obtener el dispositivo gemelo del servicio Azure IoT Hub. La información del gemelo se coloca en una variable que se puede imprimir o 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))

Revisa las propiedades de dispositivos gemelos notificados

Puede aplicar una revisión para actualizar las propiedades notificadas del dispositivo 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. Se trata de una llamada sincrónica, lo que significa que esta función no devuelve hasta que se envía la revisión al servicio y se confirma.

Si patch_twin_reported_properties devuelve un error, esta función genera el error correspondiente.

# 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)

También puede llamar a estos métodos para actualizar dispositivos gemelos:

Llame a replace_twin para reemplazar las etiquetas de dispositivo gemelo y las propiedades deseadas.
Llame a update_twin para actualizar las etiquetas de dispositivo gemelo y las propiedades deseadas.

Controlador de revisiones de propiedades deseadas entrantes

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 gemelo. 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 incluye los ejemplos siguientes:

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 back-end para:

Actualizar etiquetas gemelas y propiedades deseadas
Consultar dispositivos mediante filtros en las etiquetas y propiedades

La clase IoTHubRegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.

Conexión al centro de IoT

Puede conectar un servicio de 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. La aplicación necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crear una en caso de que no exista. Proporcione esta cadena de conexión de directiva de acceso compartido como parámetro para fromConnectionString. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

Por ejemplo:

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

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

Conexión mediante Microsoft Entra

Para obtener información general de la autenticación del SDK de Python, vea Autenticación de aplicaciones de Python en servicios de Azure mediante el SDK de Azure para Python

Configuración de la aplicación de Microsoft Entra

Secreto del cliente
Certificado
Credencial de identidad federada

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de 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 de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia de TokenCredential o reducida de ChainedTokenCredential específica. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para más información sobre las ventajas y desventajas de usar DefaultAzureCredential, vea Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para Python.

Microsoft Entra necesita 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 de Microsoft Entra, el id. de cliente y el id. de inquilino se han agregado a variables de entorno. Estas variables de entorno son usadas por DefaultAzureCredential para autenticar la aplicación. El resultado de una autenticación correcta 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 valor AccessToken resultante se puede pasar a from_token_credential a fin de conectarse a IoT Hub para cualquier cliente SDK que acepte credenciales de Microsoft Entra:

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

from_token_credential necesita dos parámetros:

URL del servicio de Azure: la URL del servicio de 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. Después, la 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 prácticos de autenticación del servicio Microsoft Entra, vea Biblioteca de autenticación de Microsoft (MSAL) para Python.

Actualizar etiquetas gemelas y propiedades deseadas

Puede actualizar las etiquetas de dispositivo gemelo y las propiedades deseadas de una aplicación back-end al mismo tiempo mediante update_twin.

Llame a get_twin para obtener la versión actual del dispositivo gemelo.
Use la clase Gemelo para agregar etiquetas y propiedades en formato JSON.
Llame a update_twin para aplicar la revisión al dispositivo gemelo. También puede usar replace_twin para reemplazar las propiedades y etiquetas deseadas de un dispositivo gemelo.

En este ejemplo se actualiza la información de etiqueta region y plant y se establece una propiedad deseada power_level en 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Creación de una consulta de dispositivo gemelo

Puede consultar la información del dispositivo gemelo mediante consultas de dispositivos gemelos. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

Para usar una consulta de dispositivo gemelo:

Use un objeto QuerySpecification para definir una solicitud de consulta similar a SQL.
Use query_iot_hub para consultar IoTHub y recuperar información de dispositivos gemelos mediante la especificación de consulta similar a SQL.

En este ejemplo se ejecutan dos consultas. La primera selecciona solo los dispositivos gemelos de los dispositivos que se encuentran en la plantaRedmond43 y la segunda mejora la consulta para seleccionar solo los dispositivos que están también conectados a través de la red de telefonía móvil. Los resultados se imprimen después de cada consulta.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

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 del dispositivo gemelo. Para obtener más información, consulte ejemplo de consulta del Administrador de registros.

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 dispositivos gemelos.

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:

Recuperar un dispositivo gemelo y examinar las propiedades notificadas
Actualizar las propiedades notificadas de dispositivos gemelos
Recibir aviso de los cambios de propiedad deseados

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. Esta sección describe el código de clase Client que se utiliza para leer y escribir datos gemelos 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 Mqtt:

npm install azure-iot-device-mqtt --save

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

Creación de un módulo de cliente

Cree un módulo Client mediante el paquete instalado.

Por ejemplo:

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

Creación de un módulo de protocolo

Cree un módulo Protocol mediante un paquete de transporte instalado.

En este ejemplo se asigna el protocolo MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

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: una cadena de conexión que encapsula los permisos "device connect" para una instancia de IoT Hub. La cadena de conexión contiene el nombre de host, la identidad del dispositivo y la clave de acceso compartido en este formato: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
transportCtor: el protocolo de transporte.

En este ejemplo se usa el protocolo de transporte Mqtt:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
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. Use .catch(err) para detectar un error y ejecutar código de controlador.

Por ejemplo:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Llame a getTwin para recuperar la información actual del dispositivo gemelo en un objeto Gemelo.

Por ejemplo:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Actualización de las propiedades notificadas de dispositivos gemelos

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 dispositivo gemelo con formato JSON en la variable patch. La revisión contiene un dispositivo gemelo connectivity valor de actualización 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.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Recibir aviso de los cambios de propiedad deseados

Cree un agente de escucha de eventos de actualización de propiedades deseada que se ejecute cuando se cambie una propiedad deseada en el dispositivo 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 una de las formas siguientes:

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

Ejemplos de SDK de dispositivos

El SDK de Azure IoT para Node.js contiene dos ejemplos de dispositivos gemelos:

Creación de una aplicación back-end

En esta sección se describe cómo crear una aplicación back-end que:

Recupera y actualiza un dispositivo gemelo.
Crea una consulta de dispositivo gemelo

Instalación de paquetes de SDK de servicio

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

npm install azure-iothub --save

La clase Registro expone todos los métodos necesarios para interactuar con dispositivos gemelos desde una aplicación back-end.

Conexión al centro de IoT

Puede conectar un servicio de 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. La aplicación necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crear una en caso de que no exista. Proporcione esta cadena de conexión de directiva de acceso compartido como parámetro para fromConnectionString. Para más información sobre las directivas de acceso compartido,vea Control del acceso a IoT Hub con firmas de acceso compartido.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Conexión mediante Microsoft Entra

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

Configuración de la aplicación de Microsoft Entra

Secreto del cliente
Certificado
Credencial de identidad federada

Para más información sobre la configuración de una aplicación de Microsoft Entra, vea Inicio rápido: Registro de 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 de back-end consiste en usar DefaultAzureCredential, pero se recomienda usar otro método en un entorno de producción, incluyendo una instancia de TokenCredential o reducida de ChainedTokenCredential específica. Para simplificar, en esta sección se describe la autenticación mediante DefaultAzureCredential y Secreto de cliente. Para más información sobre las ventajas y desventajas de usar DefaultAzureCredential, vea Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para JavaScript

Microsoft Entra necesita 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();

Después, el token de credencial resultante se puede pasar a fromTokenCredential a fin de conectarse a IoT Hub para cualquier cliente SDK que acepte las credenciales de Microsoft Entra:

fromTokenCredential necesita dos parámetros:

URL del servicio de Azure: la URL del servicio de 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. Después, la 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 prácticos de autenticación del servicio Microsoft Entra, vea Ejemplos de identidad de Azure.

Recuperación y actualización de un dispositivo gemelo

Puede crear una revisión que contenga actualizaciones de etiquetas y propiedades deseadas para un dispositivo gemelo.

Para actualizar un dispositivo gemelo:

Llame a getTwin para recuperar el objeto de dispositivo gemelo.

Formatee una revisión que contenga la actualización del dispositivo gemelo. La revisión tiene el formato JSON tal como se describe en la clase Gemelo. Una revisión del servicio back-end puede contener actualizaciones de propiedades deseadas y etiquetas. Para obtener más información sobre el formato de revisión, consulte Formato de etiquetas y propiedades.

Llame a actualizar para actualizar el dispositivo gemelo con la revisión.

En este ejemplo, el dispositivo gemelo se recupera para myDeviceId y, a continuación, se aplica una revisión a los gemelos que contienen location actualización de etiquetas de region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Creación de una consulta de dispositivo gemelo

Puede crear consultas de dispositivo similares a SQL para recopilar información de dispositivos gemelos.

Use createQuery para crear una consulta que se pueda ejecutar en una instancia de IoT Hub para buscar información sobre dispositivos o trabajos.

createQuery incluye dos parámetros:

sqlQuery: la consulta escrita como una cadena SQL.
pageSize: número deseado de resultados por página (opcional. valor predeterminado: 1000, máximo: 10000).

Si se especifica el parámetro pageSize , el objeto de consulta contiene una propiedad booleana hasMoreResults que puede comprobar y usar el método nextAsTwin para obtener la página de resultados del gemelo siguiente tantas veces como sea necesario para recuperar todos los resultados. Un método llamado next está disponible para los resultados que no son dispositivos gemelos, por ejemplo, los resultados de consultas de agregación.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Ejemplo del SDK de servicio

El SDK de Azure IoT para Node.js proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte servicio back-end de dispositivos gemelos: este proyecto se usa para enviar actualizaciones de revisiones de dispositivos gemelos para un dispositivo específico.

Compartir a través de

Introducción a los dispositivos gemelos

Requisitos previos

Información general

Creación de una aplicación de dispositivo

Agregar paquete NuGet de dispositivo

Conectarse a un dispositivo

Recuperación de un dispositivo gemelo y examen de propiedades

Actualización de las propiedades notificadas de dispositivos gemelos

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

Ejemplo de dispositivo del SDK

Creación de una aplicación back-end

Agregar paquete NuGet 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

Código de ejemplo

Leer y actualizar campos de dispositivos gemelos

Leer y actualizar etiquetas de dispositivo gemelo

Actualización de etiquetas mediante un objeto gemelo

Actualización de etiquetas mediante una cadena JSON

Visualización y actualización de las propiedades deseadas del gemelo

Otros métodos de actualización de gemelos

Creación de una consulta de dispositivo gemelo

Ejemplo del servicio SDK

Información general

Creación de una aplicación de dispositivo

Instrucciones de importación de dispositivos

Conexión del dispositivo

Recuperación y visualización de un dispositivo gemelo

Actualización de las propiedades notificadas del dispositivo gemelo

Suscripción a los cambios de propiedad deseados

Ejemplo de dispositivo del SDK

Creación de una aplicación back-end

Instrucciones de importación de servicio

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

Autenticación mediante ClientSecretCredentialBuilder

Otras clases de autenticación

Ejemplos de código

Actualizar campos gemelos de dispositivo

Creación de una consulta de dispositivo gemelo

Ejemplo del servicio SDK

Información general

Creación de una aplicación de dispositivo

Conectarse a un dispositivo

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Revisa las propiedades de dispositivos gemelos notificados

Controlador de revisiones de propiedades deseadas entrantes

Ejemplos de dispositivos del SDK

Creación de una aplicación back-end

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

Actualizar etiquetas gemelas y propiedades deseadas

Creación de una consulta de dispositivo gemelo

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 módulo de cliente

Creación de un módulo 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

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Actualización de las propiedades notificadas de dispositivos gemelos

Recibir aviso de los cambios de propiedad deseados

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

Ejemplos de SDK de dispositivos