Introducción a los dispositivos gemelos (.NET)

Artículo
03/20/2023

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.

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.

Use los 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.

Los dispositivos gemelos están diseñados para la sincronización y para consultar las condiciones y configuraciones del dispositivo. Para obtener más información sobre los dispositivos gemelos, incluyendo cuándo usarlos, consulte Comprenda los dispositivos gemelos.

Los centros de IoT almacenan dispositivos gemelos, que contienen los siguientes elementos:

Etiquetas. Metadatos de dispositivo a los que solo puede acceder el back-end de la solución.
Propiedades deseadas. Objetos JSON que puede modificar el back-end de la solución y puede observar la aplicación del dispositivo.
Propiedades notificadas. Objetos JSON que puede modificar la aplicación del dispositivo y que puede leer el back-end de la solución.

Las etiquetas y las propiedades no pueden contener matrices, pero pueden contener objetos anidados.

En la ilustración siguiente se muestra la organización del dispositivo gemelo:

Captura de pantalla de un diagrama de concepto de dispositivo gemelo.

Además, el back-end de la solución puede consultar los dispositivos gemelos en función de todos los datos descritos anteriormente. Para obtener más información acerca de los dispositivos gemelos, consulte Introducción a los dispositivos gemelos. Para más información sobre la consulta, consulte Lenguaje de consulta de IoT Hub.

En este artículo aprenderá a:

Use una aplicación de dispositivo simulado para notificar su canal de conectividad como propiedad notificada en el dispositivo gemelo.
Consultar dispositivos desde la aplicación de back-end mediante filtros en las etiquetas y propiedades que se han creado anteriormente.

En este artículo, creará dos aplicaciones de consola de .NET:

AddTagsAndQuery: una aplicación de back-end que agrega etiquetas y consulta dispositivos gemelos.
ReportConnectivity: una aplicación de dispositivo simulado que se conecta al centro de IoT y notifica su condición de conectividad.

Nota

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

Requisitos previos

Visual Studio.
Una instancia de IoT Hub. Cree uno con la CLI o el Azure Portal.
Dispositivo registrado. Registre uno en el Azure Portal.
Asegúrese de que está abierto el puerto 8883 del firewall. En el ejemplo de dispositivo de este artículo se usa el protocolo MQTT, que se comunica mediante el 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).

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

En este artículo, se crea un servicio back-end que agrega propiedades deseadas a un dispositivo gemelo y luego consulta el registro de identidades para buscar todos los dispositivos con propiedades notificadas que se han actualizado en consecuencia. El servicio 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 crearla.

Para crear una directiva de acceso compartido que conceda los permisos Conexión del servicio y Lectura del Registro, y obtenga una cadena de conexión para esta directiva, siga estos pasos:

En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.
En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.
En el menú superior situado encima de la lista de directivas, seleccione Agregar una directiva de acceso compartida.
En el panelAgregar una directiva de acceso compartida de la derecha, escriba un nombre descriptivo para la directiva, por ejemplo serviceAndRegistryRead. En Permisos, seleccione Lectura del Registro y Conexión del servicio, y después seleccione Agregar.
Seleccione la directiva nueva en la lista de directivas.
Seleccione el icono de copia para Cadena de conexión principal y guarde el valor.

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

Creación de una aplicación de dispositivo que actualiza las propiedades notificadas

En esta sección, creará una aplicación de consola de .NET que se conecta al centro como myDeviceId y, luego, actualiza las propiedades notificadas para confirmar que está conectada mediante una red de telefonía móvil.

Abra Visual Studio y seleccione Crear un proyecto.
Elija Aplicación de consola (.NET Framework)y, a continuación, seleccione Siguiente.
En Configure su nuevo proyecto, asigne al proyecto el nombre ReportConnectivity y, a continuación, seleccione Siguiente.
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto ReportConnectivity y seleccione Administrar paquetes NuGet.
Mantenga la versión predeterminada de .NET Framework y seleccione Crear para crear el proyecto.
Seleccione Examinar y busque y elija Microsoft.Azure.Devices.Client. Seleccione Instalar.

Este paso permite descargar, instalar y agregar una referencia al paquete NuGet del SDK de dispositivo IoT de Azure y sus dependencias.

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

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

Agregue los campos siguientes a la clase Program . Reemplace {device connection string} por la cadena de conexión de dispositivo que vio cuando registró un dispositivo en IoT Hub:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Agregue el método siguiente a la clase Program :

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

El objeto Cliente expone todos los métodos necesarios para interactuar con dispositivos gemelos del dispositivo. El código mostrado anteriormente, inicializa el objeto Client y, luego, recupera el dispositivo gemelo para myDeviceId.

Agregue el método siguiente a la clase Program :

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

El código anterior actualiza la propiedad notificada de myDeviceId con la información de conectividad.

Por último, agregue las líneas siguientes al método Main :

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

En el Explorador de soluciones, haga clic con el botón derecho en la solución y seleccione Establecer proyectos de inicio.
En Propiedades comunes>Proyecto de inicio, seleccione Proyectos de inicio múltiples. En ReportConnectivity, seleccione Iniciar como Acción. Seleccione Aceptar para guardar los cambios.
Ejecute esta aplicación haciendo clic con el botón derecho en el proyecto ReportConnectivity y seleccionando Depurar, seguido de Iniciar nueva instancia. Debería ver cómo obtiene la información del gemelo y, luego, cómo envía la conectividad como una propiedad notificada.

Una vez que el dispositivo ha informado sobre su información de conectividad, debe aparecer en ambas consultas.
Haga clic con el botón derecho en el proyecto AddTagsAndQuery y seleccione Depurar>Iniciar nueva instancia para volver a ejecutar las consultas. Esta vez myDeviceId debe aparecer en los resultados de ambas consultas.

Creación de una aplicación de servicio que actualiza las propiedades deseadas y consulta gemelos

En esta sección, creará una aplicación de consola de .NET que usa C# y agrega metadatos de ubicación al dispositivo gemelo asociado con myDeviceId. La aplicación consulta el centro de IoT para los dispositivos que se encuentran en Estados Unidos y, después, consulta los dispositivos que notifican una conexión de red de telefonía móvil.

En Visual Studio, seleccione Archivo > Nuevo > Proyecto. En Crear un proyecto, seleccione Aplicación de consola (.NET Framework) y seleccione Siguiente.
En Configurar el nuevo proyecto, asigne al proyecto el nombre AddTagsAndQuery y, luego, seleccione Siguiente.
Acepte la versión predeterminada de .NET Framework y seleccione Crear para crear el proyecto.
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto AddTagsAndQuery y luego seleccione Administrar paquetes NuGet.
Seleccione Examinar y busque y seleccione Microsoft.Azure.Devices. Seleccione Instalar.

Este paso permite descargar, instalar y agregar una referencia al paquete NuGet del SDK de servicio IoT de Azure y sus dependencias.
Agregue las siguientes instrucciones using al principio del archivo Program.cs :
```
using Microsoft.Azure.Devices;
```
Agregue los campos siguientes a la clase Program . Reemplace {iot hub connection string} por la cadena de conexión de IoT Hub que copió en Obtención de la cadena de conexión de IoT Hub.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Agregue el método siguiente a la clase Program :
```
public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

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

    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)));
}
```
La clase RegistryManager expone todos los métodos necesarios para interactuar con dispositivos gemelos del servicio. El código anterior inicializa primero el objeto registryManager, luego recupera el dispositivo gemelo de myDeviceId y, por último, actualiza sus etiquetas con la información de la ubicación deseada.

Después de la actualización, ejecuta dos consultas: la primera selecciona solo los dispositivos gemelos que se encuentran en la planta Redmond43 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.

El código anterior, cuando crea el objeto de consulta, especifica un número máximo de documentos devueltos. El objeto consulta contiene una propiedad booleana HasMoreResults que puede utilizar para invocar a los métodos GetNextAsTwinAsync varias veces para recuperar todos los resultados. Un método llamado GetNextAsJson está disponible para los resultados que no son dispositivos gemelos, por ejemplo, los resultados de consultas de agregación.

Por último, agregue las líneas siguientes al método Main :

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Ejecute esta aplicación haciendo clic con el botón derecho en el proyecto AddTagsAndQuery y seleccionando Depurar, seguido de Iniciar nueva instancia. Debería ver un dispositivo en los resultados de la consulta que pregunta por todos los dispositivos que se encuentran en Redmond43 y ninguno para la consulta que restringe los resultados a los dispositivos que utilizan una red de telefonía móvil.

En este artículo:

Ha agregado metadatos de dispositivo como etiquetas desde una aplicación de back-end.
Ha notificado la información de conectividad del dispositivo en el dispositivo gemelo.
Ha consultado la información del dispositivo gemelo mediante el lenguaje de consulta de IoT Hub de tipo SQL.

Pasos siguientes

Para saber cómo:

Enviar datos de telemetría desde dispositivos, consulte Inicio rápido: Envío de telemetría desde un dispositivo IoT Plug and Play a Azure IoT Hub.
Configurar dispositivos mediante las propiedades deseadas del dispositivo gemelo, consulte Tutorial: Configuración de dispositivos desde un servicio back-end.
Controlar los dispositivos de forma interactiva, por ejemplo, encender un ventilador desde una aplicación controlada por el usuario, consulte Inicio rápido: Control de un dispositivo conectado a IoT Hub.