Introducción a los dispositivos gemelos (Node.js)

Artículo
03/18/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 Node.js:

AddTagsAndQuery.js: una aplicación de back-end que agrega etiquetas y consulta dispositivos gemelos.
TwinSimulatedDevice.js: 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.

Prerrequisitos

Para completar este artículo, necesitará lo siguiente:

Una instancia de IoT Hub. Cree uno con la CLI o el Azure Portal.
Dispositivo registrado. Registre uno en el Azure Portal.
Node.js versión 10.0.x o posteriores.
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 Node.js que se conecta al centro como myDeviceId, y luego actualiza las propiedades notificadas de su dispositivo gemelo para confirmar que está conectada mediante una red de telefonía móvil.

Cree una nueva carpeta vacía denominada reportconnectivity. En la carpeta reportconnectivity , cree un nuevo archivo package.json con el siguiente comando en el símbolo del sistema. El parámetro --yes acepta todos los valores predeterminados.
```
npm init --yes
```
En el símbolo del sistema, en la carpeta reportconnectivity, ejecute el siguiente comando para instalar azure-iot-device y el paquete azure-iot-device-mqtt:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Con un editor de texto, cree un nuevo archivo ReportConnectivity.js en la carpeta reportconnectivity.

Agregue el código siguiente al archivo ReportConnectivity.js. Reemplace {device connection string} por la cadena de conexión de dispositivo que vio cuando registró un dispositivo en IoT Hub:

    'use strict';
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            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();
                }
            });
        }
        });
    }
    });

El objeto Cliente expone todos los métodos necesarios para interactuar con dispositivos gemelos del dispositivo. El código anterior, una vez que inicialice el objeto Cliente, recupera el dispositivo gemelo de myDeviceId, y actualiza su propiedad notificada con la información de conectividad.

Ejecute la aplicación del dispositivo
```
    node ReportConnectivity.js
```
Verá el mensaje twin state reported.
Ahora que el dispositivo ha informado sobre su información de conectividad, debe aparecer en ambas consultas. Vuelva a la carpeta addtagsandqueryapp y vuelva a ejecutar las consultas:
```
    node AddTagsAndQuery.js
```
Esta vez myDeviceId debe aparecer en los resultados de ambas consulta.

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 Node.js que 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.

Cree una nueva carpeta vacía denominada addtagsandqueryapp. En la carpeta addtagsandqueryapp , cree un nuevo archivo package.json con el siguiente comando en el símbolo del sistema. El parámetro --yes acepta todos los valores predeterminados.
```
npm init --yes
```
En el símbolo del sistema, en la carpeta addtagsandqueryapp, ejecute el siguiente comando para instalar el paquete azure-iothub:
```
npm install azure-iothub --save
```
Con un editor de texto, cree un nuevo archivo AddTagsAndQuery.js en la carpeta addtagsandqueryapp.

Agregue el código siguiente al archivo AddTagsAndQuery.js. 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.

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

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

El objeto Registro expone todos los métodos necesarios para interactuar con dispositivos gemelos del servicio. El código anterior inicializa primero el objeto Registro, a continuación, recupera el dispositivo gemelo de myDeviceId, y por último actualiza sus etiquetas con la información de la ubicación deseada.

Después de actualizar las etiquetas, llama a la función queryTwins.

Agregue el código siguiente al final de AddTagsAndQuery.js para implementar la función queryTwins:

     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(','));
             }
         });

         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 código anterior 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.

Cuando el código crea el objeto consulta, especifica el número máximo de documentos devueltos en el segundo parámetro. El objeto consulta contiene una propiedad booleana hasMoreResults que puede utilizar para invocar a los métodos nextAsTwin varias veces para recuperar todos los resultados. Un método llamado siguiente está disponible para los resultados que no son dispositivos gemelos, por ejemplo, los resultados de consultas de agregación.

Ejecute la aplicación con:
```
    node AddTagsAndQuery.js
```
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.