Introducción a la administración de dispositivos (Node.js)Get started with device management (Node.js)

Las aplicaciones de back-end pueden usar primitivos de Azure IoT Hub, por ejemplo, dispositivos gemelos y métodos directos, para iniciar y supervisar de forma remota las acciones de administración de dispositivos en los dispositivos.Back-end apps can use Azure IoT Hub primitives, such as device twin and direct methods, to remotely start and monitor device management actions on devices. Este tutorial muestra cómo una aplicación back-end y un dispositivo pueden trabajar juntos para iniciar y supervisar el reinicio remoto de un dispositivo mediante IoT Hub.This tutorial shows you how a back-end app and a device app can work together to initiate and monitor a remote device reboot using IoT Hub.

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 un método directo para iniciar acciones de administración de dispositivos (por ejemplo, reinicio, restablecimiento de fábrica y actualización de firmware) desde una aplicación back-end en la nube.Use a direct method to initiate device management actions (such as reboot, factory reset, and firmware update) from a back-end app in the cloud. El dispositivo es responsable de:The device is responsible for:

  • Controlar la solicitud del método enviada desde IoT Hub.Handling the method request sent from IoT Hub.

  • Iniciar la acción específica del dispositivo correspondiente en el dispositivo.Initiating the corresponding device-specific action on the device.

  • Proporcionar actualizaciones de estado mediante las propiedades notificadas a IoT Hub.Providing status updates through reported properties to IoT Hub.

Puede usar una aplicación de back-end en la nube para ejecutar consultas de dispositivos gemelos para informar sobre el progreso de las acciones de administración de los dispositivos.You can use a back-end app in the cloud to run device twin queries to report on the progress of your device management actions.

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

  • Usar Azure Portal para crear una instancia de IoT Hub y una identidad de dispositivo en ella.Use the Azure portal to create an IoT Hub and create a device identity in your IoT hub.

  • Crear una aplicación de dispositivo simulado que contiene un método directo que reinicia ese dispositivo.Create a simulated device app that contains a direct method that reboots that device. Los métodos directos se invocan desde la nube.Direct methods are invoked from the cloud.

  • Crear una aplicación de consola de Node.js que llame a un método directo de reinicio en la aplicación de dispositivo simulado mediante su centro de IoT Hub.Create a Node.js console app that calls the reboot direct method in the simulated device app through your IoT hub.

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

  • dmpatterns_getstarted_device.js, que se conecta al IoT Hub con la identidad del dispositivo creada anteriormente, recibe un método directo de reinicio, simula un reinicio físico y notifica la hora del último reinicio.dmpatterns_getstarted_device.js, which connects to your IoT hub with the device identity created earlier, receives a reboot direct method, simulates a physical reboot, and reports the time for the last reboot.

  • dmpatterns_getstarted_service.js, que llama a un método directo en la aplicación de dispositivo simulado, muestra la respuesta y muestra las propiedades notificadas actualizadas.dmpatterns_getstarted_service.js, which calls a direct method in the simulated device app, displays the response, and displays the updated reported properties.

Requisitos previosPrerequisites

  • Node.js versión 10.0.x o posteriores.Node.js version 10.0.x or later. En Preparación del entorno de desarrollo se describe cómo instalar Node.js para este tutorial en Windows o Linux.Prepare your development environment describes how to install Node.js for this tutorial on either Windows or Linux.

  • 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 el 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.

Creación de una aplicación de dispositivo simuladoCreate a simulated device app

En esta sección:In this section, you:

  • Creará una aplicación de consola de Node.js que responda a un método directo que se llama desde la nube.Create a Node.js console app that responds to a direct method called by the cloud

  • Desencadenará un reinicio del dispositivo simulado.Trigger a simulated device reboot

  • Usará las propiedades notificadas para permitir consultas de dispositivo gemelo a fin de identificar los dispositivos y cuándo se reiniciaron por última vez.Use the reported properties to enable device twin queries to identify devices and when they last rebooted

  1. Cree una nueva carpeta vacía denominada manageddevice.Create an empty folder called manageddevice. En la carpeta manageddevice , cree un archivo package.json con el siguiente comando en el símbolo del sistema.In the manageddevice folder, create a package.json file using the following command at your command prompt. Acepte todos los valores predeterminados:Accept all the defaults:

    npm init
    
  2. En el símbolo del sistema, en la carpeta manageddevice, ejecute el siguiente comando para instalar el paquete del SDK de dispositivo azure-iot-device y el paquete azure-iot-device-mqtt:At your command prompt in the manageddevice folder, run the following command to install the azure-iot-device Device SDK package and azure-iot-device-mqtt package:

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

  4. Agregue las siguientes instrucciones "require" al principio del archivo dmpatterns_getstarted_device.js:Add the following 'require' statements at the start of the dmpatterns_getstarted_device.js file:

    'use strict';
    
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;
    
  5. Agregue una variable connectionString y utilícela para crear una instancia de cliente.Add a connectionString variable and use it to create a Client instance. Reemplace el valor del marcador de posición {yourdeviceconnectionstring} por la cadena de conexión de dispositivo que copió anteriormente en Registro de un nuevo dispositivo en el centro de IoT.Replace the {yourdeviceconnectionstring} placeholder value with the device connection string you copied previously in Register a new device in the IoT hub.

    var connectionString = '{yourdeviceconnectionstring}';
    var client = Client.fromConnectionString(connectionString, Protocol);
    
  6. Agregue la siguiente función para implementar el método directo en el dispositivoAdd the following function to implement the direct method on the device

    var onReboot = function(request, response) {
    
        // Respond the cloud app for the direct method
        response.send(200, 'Reboot started', function(err) {
            if (err) {
                console.error('An error occurred when sending a method response:\n' + err.toString());
            } else {
                console.log('Response to method \'' + request.methodName + '\' sent successfully.');
            }
        });
    
        // Report the reboot before the physical restart
        var date = new Date();
        var patch = {
            iothubDM : {
                reboot : {
                    lastReboot : date.toISOString(),
                }
            }
        };
    
        // Get device Twin
        client.getTwin(function(err, twin) {
            if (err) {
                console.error('could not get twin');
            } else {
                console.log('twin acquired');
                twin.properties.reported.update(patch, function(err) {
                    if (err) throw err;
                    console.log('Device reboot twin state reported')
                });  
            }
        });
    
        // Add your device's reboot API for physical restart.
        console.log('Rebooting!');
    };
    
  7. Abra la conexión al IoT Hub e inicie la escucha del método directo:Open the connection to your IoT hub and start the direct method listener:

    client.open(function(err) {
        if (err) {
            console.error('Could not open IotHub client');
        }  else {
            console.log('Client opened.  Waiting for reboot method.');
            client.onDeviceMethod('reboot', onReboot);
        }
    });
    
  8. Guarde y cierre el archivo dmpatterns_getstarted_device.js.Save and close the dmpatterns_getstarted_device.js file.

Nota

Por simplificar, este tutorial no implementa ninguna directiva de reintentos.To keep things simple, this tutorial does not implement any retry policy. En el código de producción, deberá implementar directivas de reintentos (por ejemplo, retroceso exponencial), tal y como se sugiere en el artículo Control de errores transitorios.In production code, you should implement retry policies (such as an exponential backoff), as suggested in the article, Transient Fault Handling.

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

En este artículo, creará un servicio back-end que invoca un método directo en un dispositivo.In this article, you create a backend service that invokes a direct method on a device. Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio.To invoke a direct method on a device through IoT Hub, your service needs the service connect permission. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.By default, every IoT Hub is created with a shared access policy named service that grants this permission.

Para obtener la cadena de conexión de IoT Hub para la directiva service, siga estos pasos:To get the IoT Hub connection string for the service 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 de IoT Hub, seleccione Directivas de acceso compartido.On the left-side pane of your IoT hub, select Shared access policies.

  3. En la lista de directivas, seleccione la directiva service.From the list of policies, select the service policy.

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

Desencadenar un reinicio remoto en el dispositivo con un método directoTrigger a remote reboot on the device using a direct method

En esta sección, creará una aplicación de consola de Node.js que inicia un reinicio remoto en un dispositivo mediante un método directo.In this section, you create a Node.js console app that initiates a remote reboot on a device using a direct method. La aplicación usa las consultas gemelas de dispositivo para detectar la hora en que se reinició por última vez el dispositivo.The app uses device twin queries to discover the last reboot time for that device.

  1. Cree una carpeta vacía denominada triggerrebootondevice.Create an empty folder called triggerrebootondevice. En la carpeta triggerrebootondevice, cree un archivo package.json con el siguiente comando en el símbolo del sistema.In the triggerrebootondevice folder, create a package.json file using the following command at your command prompt. Acepte todos los valores predeterminados:Accept all the defaults:

    npm init
    
  2. En el símbolo del sistema, en la carpeta triggerrebootondevice, ejecute el siguiente comando para instalar el paquete del SDK de dispositivo azure-iothub y el paquete azure-iot-device-mqtt:At your command prompt in the triggerrebootondevice folder, run the following command to install the azure-iothub Device SDK package and azure-iot-device-mqtt package:

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

  4. Agregue las siguientes instrucciones "require" al principio del archivo dmpatterns_getstarted_service.js:Add the following 'require' statements at the start of the dmpatterns_getstarted_service.js file:

    'use strict';
    
    var Registry = require('azure-iothub').Registry;
    var Client = require('azure-iothub').Client;
    
  5. Agregue las declaraciones de variantes siguientes y reemplace el valor del marcador de posición {iothubconnectionstring} por la cadena de conexión del centro de IoT que copió anteriormente en Obtención de la cadena de conexión de IoT Hub:Add the following variable declarations and replace the {iothubconnectionstring} placeholder value with the IoT hub connection string you copied previously in Get the IoT hub connection string:

    var connectionString = '{iothubconnectionstring}';
    var registry = Registry.fromConnectionString(connectionString);
    var client = Client.fromConnectionString(connectionString);
    var deviceToReboot = 'myDeviceId';
    
  6. Agregue la siguiente función para invocar el método del dispositivo con el fin de reiniciar el dispositivo de destino:Add the following function to invoke the device method to reboot the target device:

    var startRebootDevice = function(twin) {
    
        var methodName = "reboot";
    
        var methodParams = {
            methodName: methodName,
            payload: null,
            timeoutInSeconds: 30
        };
    
        client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
            if (err) {
                console.error("Direct method error: "+err.message);
            } else {
                console.log("Successfully invoked the device to reboot.");  
            }
        });
    };
    
  7. Agregue la siguiente función para consultar el dispositivo y obtener la última hora de reinicio:Add the following function to query for the device and get the last reboot time:

    var queryTwinLastReboot = function() {
    
        registry.getTwin(deviceToReboot, function(err, twin){
    
            if (twin.properties.reported.iothubDM != null)
            {
                if (err) {
                    console.error('Could not query twins: ' + err.constructor.name + ': ' + err.message);
                } else {
                    var lastRebootTime = twin.properties.reported.iothubDM.reboot.lastReboot;
                    console.log('Last reboot time: ' + JSON.stringify(lastRebootTime, null, 2));
                }
            } else 
                console.log('Waiting for device to report last reboot time.');
        });
    };
    
  8. Agregue el siguiente código para llamar a las funciones que desencadenan el método directo de reinicio y la consulta de última hora de reinicio:Add the following code to call the functions that trigger the reboot direct method and query for the last reboot time:

    startRebootDevice();
    setInterval(queryTwinLastReboot, 2000);
    
  9. Guarde y cierre el archivo dmpatterns_getstarted_service.js.Save and close the dmpatterns_getstarted_service.js file.

Ejecución de las aplicacionesRun the apps

Ya está preparado para ejecutar las aplicaciones.You're now ready to run the apps.

  1. En el símbolo del sistema dentro de la carpeta manageddevice, ejecute el siguiente comando para iniciar la escucha del método directo de reinicio.At the command prompt in the manageddevice folder, run the following command to begin listening for the reboot direct method.

    node dmpatterns_getstarted_device.js
    
  2. En el símbolo del sistema dentro de la carpeta triggerrebootondevice, ejecute el siguiente comando para desencadenar el reinicio remoto y la consulta en el dispositivo gemelo para buscar la hora del último reinicio.At the command prompt in the triggerrebootondevice folder, run the following command to trigger the remote reboot and query for the device twin to find the last reboot time.

    node dmpatterns_getstarted_service.js
    
  3. Verá la respuesta del dispositivo al método directo de reinicio y el estado del reinicio en la consola.You see the device response to the reboot direct method and the reboot status in the console.

    A continuación, puede ver la respuesta del dispositivo al método directo de reinicio que envía el servicio:The following shows the device response to the reboot direct method sent by the service:

    salida de la aplicación manageddevice

    A continuación se muestra el servicio que desencadena el reinicio y sondea el dispositivo gemelo para la hora del último reinicio:The following shows the service triggering the reboot and polling the device twin for the last reboot time:

    salida de la aplicación triggerrebootondevice

Personalizar y ampliar el dispositivo las acciones de administración del dispositivoCustomize and extend the device management actions

Las soluciones de IoT pueden expandir el conjunto definido de patrones de administración de dispositivos o permitir modelos personalizados mediante el uso de los primitivos de método de nube a dispositivo y dispositivos gemelos.Your IoT solutions can expand the defined set of device management patterns or enable custom patterns by using the device twin and cloud-to-device method primitives. Otros ejemplos de acciones de administración de dispositivos son el restablecimiento de fábrica, la actualización de firmware, la actualización de software, la administración de energía, la administración de conectividad y red, y el cifrado de datos.Other examples of device management actions include factory reset, firmware update, software update, power management, network and connectivity management, and data encryption.

Ventanas de mantenimiento del dispositivoDevice maintenance windows

Normalmente, puede dispositivos para llevar a cabo acciones a la vez que minimiza las interrupciones y el tiempo de inactividad.Typically, you configure devices to perform actions at a time that minimizes interruptions and downtime. Las ventanas de mantenimiento dle dispositivo son un patrón que se utiliza habitualmente para definir la hora en la que un dispositivo debe actualizar su configuración.Device maintenance windows are a commonly used pattern to define the time when a device should update its configuration. Las soluciones de back-end pueden utilizar las propiedades deseadas del dispositivo gemelo para definir y activar una directiva en el dispositivo que permita una ventana de mantenimiento.Your back-end solutions can use the desired properties of the device twin to define and activate a policy on your device that enables a maintenance window. Cuando un dispositivo recibe la directiva de la ventana de mantenimiento, puede usar la propiedad notificada del dispositivo gemelo para informar del estado de la directiva.When a device receives the maintenance window policy, it can use the reported property of the device twin to report the status of the policy. La aplicación de back-end puede usar luego consultas de dispositivos gemelos para dar testimonio de cumplimiento de dispositivos y cada directiva.The back-end app can then use device twin queries to attest to compliance of devices and each policy.

Pasos siguientesNext steps

En este tutorial se usó un método directo para desencadenar un reinicio remoto en un dispositivo.In this tutorial, you used a direct method to trigger a remote reboot on a device. Se usaron las propiedades notificadas para notificar la última hora de reinicio del dispositivo y se consultó el dispositivo gemelo para detectar la última hora de reinicio del dispositivo desde la nube.You used the reported properties to report the last reboot time from the device, and queried the device twin to discover the last reboot time of the device from the cloud.

Para continuar con la introducción de IoT Hub y los patrones de administración de dispositivos como remotos a través de la actualización de firmware de aire, vea Realización de una actualización de firmware.To continue getting started with IoT Hub and device management patterns such as remote over the air firmware update, see How to do a firmware update.

Para obtener información sobre cómo ampliar la solución IoT y programar llamadas a métodos en varios dispositivos, vea Programación de trabajos en varios dispositivos.To learn how to extend your IoT solution and schedule method calls on multiple devices, see Schedule and broadcast jobs.