Este explorador ya no se admite.
Actualice a Microsoft Edge para aprovechar las características y actualizaciones de seguridad más recientes, y disponer de soporte técnico.
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:
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:
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.
Un centro de IoT
Un dispositivo registrado
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).
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.
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:
Las aplicaciones cliente de dispositivo escritas en C# requieren el paquete NuGet Microsoft.Azure.Devices.Client.
Agregue esta instrucción using para usar la biblioteca de dispositivos.
using Microsoft.Azure.Devices.Client;
Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:
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.
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 CreateFromConnectionStringTransportType admite los siguientes protocolos de transporte:
MqttMqtt_WebSocket_OnlyMqtt_Tcp_OnlyAmqpAmqp_WebSocket_OnlyAmqp_Tcp_OnlyEl 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);
Para conectar un dispositivo a IoT Hub mediante un certificado X.509:
Use DeviceAuthenticationWithX509Certificate para crear un objeto que contenga la información del dispositivo y del certificado.
DeviceAuthenticationWithX509Certificate se pasa como segundo parámetro a DeviceClient.Create (paso 2).
Use DeviceClient.Create para conectar el dispositivo a IoT Hub mediante un certificado X.509.
En este ejemplo, la información del dispositivo y del certificado se rellena en el objeto authDeviceAuthenticationWithX509Certificate que se pasa a DeviceClient.Create.
En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use Environment.GetEnvironmentVariable("HOSTNAME") para leer la variable de entorno de nombre de host.
RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";
var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);
using var deviceClient = DeviceClient.Create(
HostName,
auth,
TransportType.Amqp);
Para obtener más información acerca de la autenticación de certificado, vea:
Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte:
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()}");
Para actualizar una propiedad notificada de gemelo:
TwinCollectionPor 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);
}
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);
}
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.
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:
La clase RegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.
Las aplicaciones de servicio back-end requieren el paquete NuGet de Microsoft.Azure.Devices.
Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:
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.
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);
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.
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:
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.
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:
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);
Para obtener un ejemplo práctico de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.
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.
Utilice la propiedad del dispositivo gemelo Etiquetas para leer y escribir la información de las etiquetas del dispositivo.
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);
}
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);
}
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);
También puede aplicar actualizaciones de gemelos mediante estos métodos del SDK:
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.
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)));
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.
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.
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 crear código de aplicación de dispositivo para:
La clase DeviceClient expone todos los métodos necesarios para interactuar con dispositivos gemelos desde el dispositivo.
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.
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.*;
Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:
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.
Para conectar un dispositivo a IoT Hub:
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);
Para conectar un dispositivo a IoT Hub mediante un certificado X.509:
SSLContext a un objeto ClientOptions.ClientOptions para crear la conexión del dispositivo a IoT Hub.En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use Environment.GetEnvironmentVariable("PUBLICKEY") para leer una variable de entorno de cadena de certificado de clave pública.
private static final String publicKeyCertificateString =
"-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
//PEM encoded representation of the private key
private static final String privateKeyString =
"-----BEGIN EC PRIVATE KEY-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END EC PRIVATE KEY-----\n";
SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);
Para obtener más información acerca de la autenticación de certificado, vea:
Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte:
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);
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);
}
}
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.
En esta sección se describe cómo crear una aplicación back-end que:
La clase ServiceClientDeviceTwin contiene métodos que los servicios pueden utilizar para acceder a los dispositivos gemelos.
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;
Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:
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.
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);
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.
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.
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:
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.
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();
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();
El SDK de Java también incluye estas clases que autentican una aplicación de back-end con Microsoft Entra:
Para obtener ejemplos prácticos de autenticación de servicios de Microsoft Entra, vea Ejemplo de autenticación basada en roles.
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);
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());
}
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.
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.
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
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.
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:
Agregue este código para importar las funciones IoTHubDeviceClient desde el SDK azure.iot.device.
from azure.iot.device import IoTHubDeviceClient
Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:
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.
Para conectar un dispositivo a IoT Hub:
Por ejemplo:
# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
# Connect the client
device_client.connect()
Para conectar un dispositivo a IoT Hub mediante un certificado X.509:
En este ejemplo, se muestran los valores de parámetros de entrada de certificado como variables locales para mayor claridad. En un sistema de producción, almacene parámetros de entrada confidenciales en variables de entorno u otra ubicación de almacenamiento más segura. Por ejemplo, use os.getenv("HOSTNAME") para leer la variable de entorno de nombre de host.
# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"
# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"
# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"
x509 = X509(
cert_file,
key_file,
pass_phrase,
)
# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
hostname=hostname, device_id=device_id, x509=x509
)
# Connect to IoT Hub
await device_client.connect()
Para obtener más información acerca de la autenticación de certificado, vea:
Para obtener ejemplos funcionales de autenticación de certificados X.509 de dispositivo, consulte los ejemplos cuyos nombres de archivo terminan en x509 en escenarios del centro de Async.
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))
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:
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 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)
El SDK de Azure IoT para Python incluye los ejemplos siguientes:
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 una aplicación back-end para:
La clase IoTHubRegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.
Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:
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.
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)
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.
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
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:
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.
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.
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 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:
from_token_credential necesita dos parámetros:
{Your Entra domain URL}.azure-devices.net sin un prefijo https://. Por ejemplo, MyAzureDomain.azure-devices.net.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)
Para obtener ejemplos prácticos de autenticación del servicio Microsoft Entra, vea Biblioteca de autenticación de Microsoft (MSAL) para Python.
Puede actualizar las etiquetas de dispositivo gemelo y las propiedades deseadas de una aplicación back-end al mismo tiempo mediante update_twin.
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)
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()
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.
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.
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 paquete de azure-iot-device en el SDK de Azure IoT para Node.js para crear una aplicación de dispositivo para:
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.
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
Una aplicación de dispositivo se puede autenticar con IoT Hub mediante los métodos siguientes:
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.
El certificado X.509 está asociado al transporte de conexión del dispositivo a IoT Hub.
Para configurar la conexión de un dispositivo a IoT Hub mediante un certificado X.509:
Llame a fromConnectionString para agregar la cadena de conexión del dispositivo o del módulo de identidad y el tipo de transporte al objeto Client. Agregue x509=true a la cadena de conexión para indicar que se agrega un certificado a DeviceClientOptions. Por ejemplo:
Una cadena de conexión de dispositivo:
HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Una cadena de conexión del módulo de identidad:
HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Configure una variable JSON con detalles del certificado y pásela a DeviceClientOptions.
Llame a setOptions para agregar un certificado y una clave X.509 (y, opcionalmente, una frase de contraseña) al transporte del cliente.
Llame a open para abrir la conexión desde el dispositivo a IoT Hub.
En este ejemplo, se muestra información de configuración del certificado dentro de una variable JSON. La configuración de certificación clientOptions se pasa a setOptions y la conexión se abre mediante open.
const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);
var clientOptions = {
cert: myX509Certificate,
key: myX509Key,
passphrase: passphrase,
http: {
receivePolicy: {
interval: 10
}
}
}
client.setOptions(clientOptions);
client.open(connectCallback);
Para obtener más información acerca de la autenticación de certificado, vea:
Para obtener un ejemplo funcional de autenticación de certificados X.509 de dispositivo, consulte Ejemplo de X.509 de dispositivo simple.
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.
EClientl objeto admite estos protocolos:
AmqpHttp: al usar Http, la instancia de Client comprueba si hay mensajes de IoT Hub con poca frecuencia (cada 25 minutos como mínimo).MqttMqttWsAmqpWsInstale 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.
Cree un módulo Client mediante el paquete instalado.
Por ejemplo:
const Client = require('azure-iot-device').Client;
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;
Llame a fromConnectionString para proporcionar parámetros de conexión de dispositivo:
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);
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);
});
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');
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();
}
});
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:
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));
});
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);
}
});
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);
});
El SDK de Azure IoT para Node.js contiene dos ejemplos de dispositivos gemelos:
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 una aplicación back-end que:
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.
Puede conectar un servicio de back-end a IoT Hub mediante los siguientes métodos:
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.
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);
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.
Para obtener información general sobre la autenticación del SDK de Node.js, vea lo siguiente:
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:
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.
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
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 este paquete:
npm install --save @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 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.
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:
{Your Entra domain URL}.azure-devices.net sin un prefijo https://. Por ejemplo, MyAzureDomain.azure-devices.net.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);
Para obtener ejemplos prácticos de autenticación del servicio Microsoft Entra, vea Ejemplos de identidad de Azure.
Puede crear una revisión que contenga actualizaciones de etiquetas y propiedades deseadas para un dispositivo gemelo.
Para actualizar un dispositivo gemelo:
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();
}
});
}
});
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:
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(','));
}
});
};
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.
Cursos
Módulo
Conexión de datos de IoT a un entorno de realidad mixta con Azure Digital Twins y Unity - Training
Transmita datos de telemetría operativos simulados de los recursos físicos a Azure Digital Twins y visualice los datos en Unity y un entorno de realidad mixta. Aprenda cómo usar una plantilla de ARM, crear una interfaz de usuario en Unity e identificar eventos de rendimiento antes de realizar la implementación en una instancia de HoloLens 2.
Documentación
Información sobre los dispositivos gemelos de Azure IoT Hub - Azure IoT Hub
En este artículo se describe cómo usar dispositivos gemelos para sincronizar los datos de estado y de configuración entre IoT Hub y sus dispositivos.
Información sobre los módulos gemelos de Azure IoT Hub
En este artículo se describe cómo usar módulos gemelos para sincronizar los datos de estado y de configuración entre IoT Hub y sus dispositivos
Administración de dispositivos y módulos mediante gemelos - Azure IoT Hub
Use Azure Portal y la CLI de Azure para consultar y actualizar dispositivos gemelos y módulos gemelos en el Azure IoT Hub.