Introducción a los dispositivos gemelos (Node.js)Get started with device twins (Node.js)

Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones.Device twins are JSON documents that store device state information, including metadata, configurations, and conditions. IoT Hub conserva un dispositivo gemelo por cada dispositivo que se conecta a él.IoT Hub persists a device twin for each device that connects to it.

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub.The features described in this article are available only in the standard tier of IoT Hub. Para más información sobre los niveles Básico y Estándar de IoT Hub, consulte el artículo sobre cómo elegir el nivel de IoT Hub correcto.For more information about the basic and standard IoT Hub tiers, see Choose the right IoT Hub tier.

Use los dispositivos gemelos para:Use device twins to:

  • Almacenar metadatos del dispositivo desde el back-end de la solución.Store device metadata from your solution back end.

  • 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.Report current state information such as available capabilities and conditions, for example, the connectivity method used, from your device app.

  • 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.Synchronize the state of long-running workflows, such as firmware and configuration updates, between a device app and a back-end app.

  • Consultar los metadatos, la configuración o el estado del dispositivo.Query your device metadata, configuration, or state.

Los dispositivos gemelos están diseñados para la sincronización y para consultar las condiciones y configuraciones del dispositivo.Device twins are designed for synchronization and for querying device configurations and conditions. Para más información sobre cuándo usar dispositivos gemelos, consulte Introducción a los dispositivos gemelos.More information on when to use device twins can be found in Understand device twins.

Los dispositivos gemelos se almacenan en un IoT Hub y contienen los elementos siguientes:Device twins are stored in an IoT hub and contain the following elements:

  • Etiquetas.Tags. Metadatos de dispositivo a los que solo puede acceder el back-end de la solución.Device metadata accessible only by the solution back end.

  • Propiedades deseadas.Desired properties. Objetos JSON que puede modificar el back-end de la solución y puede observar la aplicación del dispositivo.JSON objects modifiable by the solution back end and observable by the device app.

  • Propiedades notificadas.Reported properties. Objetos JSON que puede modificar la aplicación del dispositivo y que puede leer el back-end de la solución.JSON objects modifiable by the device app and readable by the solution back end.

Las etiquetas y propiedades no pueden contener matrices, pero se pueden anidar objetos.Tags and properties cannot contain arrays, but objects can be nested.

En la ilustración siguiente se muestra la organización del dispositivo gemelo:The following illustration shows device twin organization:

Imagen de dispositivo gemelo mostrando la funcionalidad

Además, el back-end de la solución puede consultar los dispositivos gemelos en función de todos los datos descritos anteriormente.Additionally, the solution back end can query device twins based on all the above data. Para obtener más información acerca de los dispositivos gemelos, consulte Introducción a los dispositivos gemelos.For more information about device twins, see Understand device twins. Para más información sobre la consulta, consulte Lenguaje de consulta de IoT Hub.For more information about querying, see IoT Hub query language.

En este tutorial se muestra cómo realizar las siguientes acciones:This tutorial shows you how to:

  • Crear una aplicación de back-end que agrega etiquetas a un dispositivo gemelo y una aplicación de dispositivo simulado que notifica su canal de conectividad como propiedad notificada en el dispositivo gemelo.Create a back-end app that adds tags to a device twin, and a simulated device app that reports its connectivity channel as a reported property on the device twin.

  • Consultar dispositivos desde la aplicación de back-end mediante filtros en las etiquetas y propiedades que se han creado anteriormente.Query devices from your back-end app using filters on the tags and properties previously created.

Al final de este tutorial tendrá dos aplicaciones de consola de Node.js:At the end of this tutorial, you will have two Node.js console apps:

  • AddTagsAndQuery.js, una aplicación Node.js de back-end diseñada para ejecutarse desde el back-end, que agrega etiquetas y consulta dispositivos gemelos.AddTagsAndQuery.js, a Node.js back-end app, which adds tags and queries device twins.

  • TwinSimulatedDevice.js, una aplicación de Node.js que simula un dispositivo que se conecta a su instancia de IoT Hub con la identidad del dispositivo creada anteriormente e informa de su estado de conectividad.TwinSimulatedDevice.js, a Node.js app, which simulates a device that connects to your IoT hub with the device identity created earlier, and reports its connectivity condition.

Nota

En el artículo SDK de IoT de Azure se proporciona información sobre los SDK de IoT de Azure que se pueden usar para crear aplicaciones de dispositivo y de back-end.The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both device and back-end apps.

Requisitos previosPrerequisites

Para completar este tutorial, necesita:To complete this tutorial, you need:

  • Node.js versión 10.0.x o posteriores.Node.js version 10.0.x or later.

  • Una cuenta de Azure activa.An active Azure account. (En caso de no tener ninguna, puede crear una cuenta gratuita en tan solo unos minutos).(If you don't have an account, you can create a free account in just a couple of minutes.)

Crear un centro de IoTCreate an IoT hub

En esta sección se describe cómo crear un centro de IoT mediante Azure Portal.This section describes how to create an IoT hub using the Azure portal.

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.

  2. En la página de inicio de Azure, seleccione + Crear un recurso y, después, escriba IoT Hub en el campo Buscar en Marketplace.From the Azure homepage, select the + Create a resource button, and then enter IoT Hub in the Search the Marketplace field.

  3. Seleccione IoT Hub en los resultados de la búsqueda y, después, haga clic en Crear.Select IoT Hub from the search results, and then select Create.

  4. En la pestaña Datos básicos, complete los campos como se indica a continuación:On the Basics tab, complete the fields as follows:

    • Suscripción: seleccione la suscripción que quiera usar para el centro.Subscription: Select the subscription to use for your hub.

    • Grupo de recursos: seleccione un grupo de recursos o cree uno.Resource Group: Select a resource group or create a new one. Para crear uno, haga clic en Crear y escriba el nombre que quiera usar.To create a new one, select Create new and fill in the name you want to use. Para usar un grupo de recursos existente, selecciónelo.To use an existing resource group, select that resource group. Para más información, consulte Administración de grupos de recursos de Azure Resource Manager.For more information, see Manage Azure Resource Manager resource groups.

    • Región: seleccione la región a la que quiera asignar el centro.Region: Select the region in which you want your hub to be located. Seleccione la ubicación más cercana a la suya.Select the location closest to you.

    • Nombre de la instancia de IoT Hub: escriba el nombre del centro.IoT Hub Name: Enter a name for your hub. Este nombre debe ser único globalmente.This name must be globally unique. Si el nombre que escribe está disponible, aparece una marca de verificación verde.If the name you enter is available, a green check mark appears.

    Importante

    Como el centro de IoT se podrá detectar públicamente como un punto de conexión de DNS, asegúrese de que no incluye información de identificación personal ni información confidencial al asignarle un nombre.Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

    Creación de un centro mediante Azure Portal

  5. Seleccione Siguiente: escala y tamaño para seguir creando el centro.Select Next: Size and scale to continue creating your hub.

    Configuración del tamaño y la escala de un nuevo centro de IoT mediante Azure Portal

    Esta pantalla le permite configurar los valores siguientes:This screen allows you to set the following values:

    • Plan de tarifa y escala: nivel seleccionado.Pricing and scale tier: Your selected tier. Puede elegir entre varios niveles, en función del número de características que desee, y del número de mensajes que envíe al día a través de su solución.You can choose from several tiers, depending on how many features you want and how many messages you send through your solution per day. El nivel gratis está pensado para la prueba y evaluación.The free tier is intended for testing and evaluation. Permite la conexión de 500 dispositivos con el centro de IoT y hasta 8000 mensajes al día.It allows 500 devices to be connected to the hub and up to 8,000 messages per day. Cada suscripción a Azure puede crear un centro de IoT en el nivel gratis.Each Azure subscription can create one IoT hub in the free tier.

    • Unidades de IoT Hub: El número de mensajes que se permiten por unidad al día depende del plan de tarifa del centro.IoT Hub units: The number of messages allowed per unit per day depends on your hub's pricing tier. Por ejemplo, si quiere que el Centro de IoT admita la entrada de 700 000 mensajes, seleccione dos unidades del nivel S1.For example, if you want the hub to support ingress of 700,000 messages, you choose two S1 tier units. Para más información sobre las demás opciones del nivel, consulte la sección Elección del nivel correcto de IoT Hub.For details about the other tier options, see Choosing the right IoT Hub tier.

    • Configuración avanzada > Particiones del dispositivo a la nube: esta propiedad relaciona los mensajes del dispositivo a la nube con el número de lectores simultáneos de los mensajes.Advanced Settings > Device-to-cloud partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. La mayoría de los centros solo necesitan cuatro particiones.Most hubs need only four partitions.

  6. Para este artículo, acepte las opciones predeterminadas y, después, seleccione Revisar y crear para revisar las opciones.For this article, accept the default choices, and then select Review + create to review your choices. Verá algo parecido a esta pantalla.You see something similar to this screen.

    Revisión de la información para crear el centro de IoT

  7. Seleccione Crear para crear un centro.Select Create to create your new hub. Esta operación tarda unos minutos.Creating the hub takes a few minutes.

Registro de un nuevo dispositivo en el centro de IoTRegister a new device in the IoT hub

En esta sección, se usa la CLI de Azure para crear una identidad del dispositivo para este artículo.In this section, you use the Azure CLI to create a device identity for this article. Los identificadores de dispositivos distinguen mayúsculas de minúsculas.Device IDs are case sensitive.

  1. Abra Azure Cloud Shell.Open Azure Cloud Shell.

  2. En Azure Cloud Shell, ejecute el comando siguiente para instalar la extensión IoT de Microsoft Azure para la CLI de Azure:In Azure Cloud Shell, run the following command to install the Microsoft Azure IoT Extension for Azure CLI:

    az extension add --name azure-cli-iot-ext
    
  3. Cree una identidad del dispositivo denominada myDeviceId y recupere la cadena de conexión del dispositivo con estos comandos:Create a new device identity called myDeviceId and retrieve the device connection string with these commands:

    az iot hub device-identity create --device-id myDeviceId --hub-name {Your IoT Hub name}
    az iot hub device-identity show-connection-string --device-id myDeviceId --hub-name {Your IoT Hub name} -o table
    

    Importante

    El identificador del dispositivo puede estar visible en los registros recopilados para soporte técnico y solución de problemas del cliente, por tanto asegúrese de evitar cualquier información confidencial al darle el nombre.The device ID may be visible in the logs collected for customer support and troubleshooting, so make sure to avoid any sensitive information while naming it.

Anote la cadena de conexión de dispositivo del resultado.Make a note of the device connection string from the result. La aplicación de dispositivo usa esta cadena de conexión de dispositivo para conectarse a su instancia de IoT Hub como un dispositivo.This device connection string is used by the device app to connect to your IoT Hub as a device.

Obtención de la cadena de conexión de IoT HubGet the IoT hub connection string

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.In this article, you create a back-end service that adds desired properties to a device twin and then queries the identity registry to find all devices with reported properties that have been updated accordingly. 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.Your service needs the service connect permission to modify desired properties of a device twin, and it needs the registry read permission to query the identity registry. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crearla.There is no default shared access policy that contains only these two permissions, so you need to create one.

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:To create a shared access policy that grants service connect and registry read permissions and get a connection string for this policy, follow these steps:

  1. En Azure Portal, seleccione Grupos de recursos.In the Azure portal, select Resource groups. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.Select the resource group where your hub is located, and then select your hub from the list of resources.

  2. En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.On the left-side pane of your hub, select Shared access policies.

  3. En el menú superior situado encima de la lista de directivas, seleccione Agregar.From the top menu above the list of policies, select Add.

  4. En Agregar una directiva de acceso compartida, escriba un nombre descriptivo para la directiva, por ejemplo serviceAndRegistryRead.Under Add a shared access policy, enter a descriptive name for your policy, such as serviceAndRegistryRead. En Permisos, seleccione Lectura del Registro y Conectar el servicio, y después seleccione Crear.Under Permissions, select Registry read and Service connect, and then select Create.

    Cómo agregar una nueva directiva de acceso compartido

  5. Seleccione la directiva nueva en la lista de directivas.Select your new policy from the list of policies.

  6. En Claves de acceso compartido, seleccione el icono de Cadena de conexión: clave principal y guarde el valor.Under Shared access keys, select the copy icon for the Connection string -- primary key and save the value.

    Recuperación de la cadena de conexión

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.For more information about IoT Hub shared access policies and permissions, see Access control and permissions.

Creación de la aplicación de servicioCreate the service app

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.In this section, you create a Node.js console app that adds location metadata to the device twin associated with myDeviceId. Después, consulta los dispositivos gemelos almacenados en la instancia de IoT Hub mediante la selección de los dispositivos ubicados en Estados Unidos y, después, los que informan de una conexión de red de telefonía móvil.It then queries the device twins stored in the IoT hub selecting the devices located in the US, and then the ones that are reporting a cellular connection.

  1. Cree una nueva carpeta vacía denominada addtagsandqueryapp.Create a new empty folder called addtagsandqueryapp. En la carpeta addtagsandqueryapp , cree un nuevo archivo package.json con el siguiente comando en el símbolo del sistema.In the addtagsandqueryapp folder, create a new package.json file using the following command at your command prompt. El parámetro --yes acepta todos los valores predeterminados.The --yes parameter accepts all the defaults.

    npm init --yes
    
  2. En el símbolo del sistema, en la carpeta addtagsandqueryapp, ejecute el siguiente comando para instalar el paquete azure-iothub:At your command prompt in the addtagsandqueryapp folder, run the following command to install the azure-iothub package:

    npm install azure-iothub --save
    
  3. Con un editor de texto, cree un nuevo archivo AddTagsAndQuery.js en la carpeta addtagsandqueryapp.Using a text editor, create a new AddTagsAndQuery.js file in the addtagsandqueryapp folder.

  4. Agregue el código siguiente al archivo AddTagsAndQuery.js.Add the following code to the AddTagsAndQuery.js file. 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.Replace {iot hub connection string} with the IoT Hub connection string you copied in Get the IoT hub connection string.

         '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.The Registry object exposes all the methods required to interact with device twins from the service. 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.The previous code first initializes the Registry object, then retrieves the device twin for myDeviceId, and finally updates its tags with the desired location information.

    Después de actualizar las etiquetas, llama a la función queryTwins.After updating the tags it calls the queryTwins function.

  5. Agregue el código siguiente al final de AddTagsAndQuery.js para implementar la función queryTwins:Add the following code at the end of AddTagsAndQuery.js to implement the queryTwins function:

         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.The previous code executes two queries: the first selects only the device twins of devices located in the Redmond43 plant, and the second refines the query to select only the devices that are also connected through cellular network.

    Cuando el código crea el objeto consulta, especifica el número máximo de documentos devueltos en el segundo parámetro.When the code creates the query object, it specifies the maximum number of returned documents in the second parameter. 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.The query object contains a hasMoreResults boolean property that you can use to invoke the nextAsTwin methods multiple times to retrieve all results. Un método llamado siguiente está disponible para los resultados que no son dispositivos gemelos, por ejemplo, los resultados de consultas de agregación.A method called next is available for results that are not device twins, for example, the results of aggregation queries.

  6. Ejecute la aplicación con:Run the application with:

        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.You should see one device in the results for the query asking for all devices located in Redmond43 and none for the query that restricts the results to devices that use a cellular network.

    Visualización del dispositivo en los resultados de la consulta

En la siguiente sección, creará una aplicación de dispositivo que notifica la información de conectividad y cambia el resultado de la consulta en la sección anterior.In the next section, you create a device app that reports the connectivity information and changes the result of the query in the previous section.

Creación de la aplicación del dispositivoCreate the device app

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 contener la información que está conectada mediante una red de telefonía móvil.In this section, you create a Node.js console app that connects to your hub as myDeviceId, and then updates its device twin's reported properties to contain the information that it is connected using a cellular network.

  1. Cree una nueva carpeta vacía denominada reportconnectivity.Create a new empty folder called reportconnectivity. En la carpeta reportconnectivity , cree un nuevo archivo package.json con el siguiente comando en el símbolo del sistema.In the reportconnectivity folder, create a new package.json file using the following command at your command prompt. El parámetro --yes acepta todos los valores predeterminados.The --yes parameter accepts all the defaults.

    npm init --yes
    
  2. 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:At your command prompt in the reportconnectivity folder, run the following command to install the azure-iot-device, and azure-iot-device-mqtt packages:

    npm install azure-iot-device azure-iot-device-mqtt --save
    
  3. Con un editor de texto, cree un nuevo archivo ReportConnectivity.js en la carpeta reportconnectivity.Using a text editor, create a new ReportConnectivity.js file in the reportconnectivity folder.

  4. Agregue el código siguiente al archivo ReportConnectivity.js.Add the following code to the ReportConnectivity.js file. Reemplace {device connection string} por la cadena de conexión de dispositivo que copió al crear la identidad del dispositivo myDeviceId en Registro de un nuevo dispositivo en el centro de IoT.Replace {device connection string} with the device connection string you copied when you created the myDeviceId device identity in Register a new device in the 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.The Client object exposes all the methods you require to interact with device twins from the device. 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.The previous code, after it initializes the Client object, retrieves the device twin for myDeviceId and updates its reported property with the connectivity information.

  5. Ejecute la aplicación del dispositivoRun the device app

        node ReportConnectivity.js
    

    Verá el mensaje twin state reported.You should see the message twin state reported.

  6. Ahora que el dispositivo ha informado sobre su información de conectividad, debe aparecer en ambas consultas.Now that the device reported its connectivity information, it should appear in both queries. Vuelva a la carpeta addtagsandqueryapp y vuelva a ejecutar las consultas:Go back in the addtagsandqueryapp folder and run the queries again:

        node AddTagsAndQuery.js
    

    Esta vez myDeviceId debe aparecer en los resultados de ambas consulta.This time myDeviceId should appear in both query results.

    Representación de myDeviceId en los resultados de las dos consultas

Pasos siguientesNext steps

En este tutorial, configuró un centro de IoT nuevo en Azure Portal y, después, creó una identidad de dispositivo en el registro de identidades del centro de IoT.In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT hub's identity registry. Ha agregado metadatos de dispositivo como etiquetas desde una aplicación back-end y ha escrito una aplicación de dispositivo simulado para notificar la información de conectividad de dispositivos en el dispositivo gemelo.You added device metadata as tags from a back-end app, and wrote a simulated device app to report device connectivity information in the device twin. También ha aprendido cómo consultar esta información mediante el lenguaje de consulta de IoT Hub de tipo SQL.You also learned how to query this information using the SQL-like IoT Hub query language.

Use los siguientes recursos para obtener información sobre cómo:Use the following resources to learn how to: