Introdução ao gerenciamento de dispositivos (Node.js)

Artigo
10/01/2024

Os aplicativos de back-end podem usar primitivos do Hub IoT do Azure, como dispositivos gêmeos e métodos diretos, para iniciar e monitorar remotamente as ações de gerenciamento de dispositivo nos dispositivos. Este artigo mostra como um aplicativo de back-end e um dispositivo podem trabalhar juntos para permitir que você inicie e monitore uma reinicialização remota por meio do Hub IoT.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Use um método direto para iniciar as ações de gerenciamento do dispositivo (como a reinicialização, redefinição de fábrica e atualização do firmware) a partir de um aplicativo de back-end na nuvem. O dispositivo é responsável por:

Lidar com a solicitação do método enviada a partir do Hub IoT.
Iniciar a ação específica do dispositivo correspondente no dispositivo.
Fornecimento de atualizações de status por meio das propriedades relatadas para o Hub IoT.

Você pode usar um aplicativo de back-end na nuvem para executar consultas do dispositivo gêmeo para relatar o progresso de suas ações de gerenciamento do dispositivo.

Este artigo mostra como criar:

dmpatterns_getstarted_device.js: um aplicativo de dispositivo simulado com um método direto que reinicializa o dispositivo e relata a hora da última reinicialização. Métodos diretos são invocados da nuvem.
dmpatterns_getstarted_service.js: um aplicativo de console .NET que chama o método direto no aplicativo de dispositivo simulado por meio do Hub IoT. Ele exibe a resposta e as propriedades relatadas atualizadas.

Pré-requisitos

Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo.
Node.js versão 10.0.x ou posterior. Preparar o ambiente de desenvolvimento descreve como instalar o Node.js para este artigo no Windows ou no Linux.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Criar um aplicativo de dispositivo com um método direto

Nesta seção, você:

Criar um aplicativo de console do Node.js que responde a um método direto chamado pela nuvem.
Dispare uma reinicialização do dispositivo simulado.
Usar as propriedades relatadas para habilitar consultas de dispositivo gêmeo para identificar dispositivos e a última reinicialização.

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Crie uma pasta vazia chamada managed-device. Na pasta managed-device, crie um arquivo package.json usando o comando a seguir no prompt de comando. Aceite todos os padrões:
```
npm init
```
No prompt de comando na pasta managed-device, execute o seguinte comando para instalar o pacote azure-iot-device do SDK do Dispositivo e o pacote azure-iot-device-mqtt:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Usando um editor de texto, crie um arquivo dmpatterns_getstarted_device.js na pasta managed-device.

Adicione as seguintes instruções ‘require’ no início do arquivo dmpatterns_getstarted_device.js:

'use strict';

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

Adicione uma variável connectionString e use-a para criar um Cliente do dispositivo. Substitua o valor do espaço reservado {yourdeviceconnectionstring} pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:
```
var connectionString = '{yourdeviceconnectionstring}';
var client = Client.fromConnectionString(connectionString, Protocol);
```

Adicione a seguinte função para implementar o método direto no dispositivo

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

Abra a conexão com o Hub IoT e inicie o ouvinte do método direto:

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

Salve e feche o arquivo dmpatterns_getstarted_device.js.

Observação

Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, implemente políticas de repetição (como uma retirada exponencial), conforme sugerido no artigo Tratamento de falhas transitórias.

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que invoca um método direto em um dispositivo. Para invocar um método direto em um dispositivo por meio do Hub IoT, o seu serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política de serviço, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub IoT, selecione Políticas de acesso compartilhado.
Na lista de políticas, selecione a política de serviço.
Copie a Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar um aplicativo de serviço para disparar uma reinicialização

Nesta seção, você criará um aplicativo do console Node.js que inicia uma reinicialização remota em um dispositivo usando um método direto. O aplicativo usa consultas de dispositivo gêmeo para descobrir o último horário de reinicialização para esse dispositivo.

Importante

Este artigo inclui etapas para se conectar a um serviço usando uma assinatura de acesso compartilhado. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Crie uma pasta vazia chamada trigger-reboot-on-device. Na pasta trigger-reboot-on-device, crie um arquivo package.json usando o comando a seguir no prompt de comando. Aceite todos os padrões:
```
npm init
```
No prompt de comando, na pasta trigger-reboot-on-device, execute o seguinte comando para instalar o pacote azure-iothub do SDK do Dispositivo e o pacote azure-iot-device-mqtt:
```
npm install azure-iothub --save
```
Usando um editor de texto, crie um arquivo dmpatterns_getstarted_service.js na pasta trigger-reboot-on-device.

Adicione as seguintes instruções "require" no início do arquivo dmpatterns_getstarted_service.js:

'use strict';

var Registry = require('azure-iothub').Registry;
var Client = require('azure-iothub').Client;

Adicione as seguintes declarações de variável e substitua o valor de espaço reservado {iothubconnectionstring} pela cadeia de conexão do hub IoT que você copiou anteriormente em Obter a cadeia de conexão do hub IoT:
```
var connectionString = '{iothubconnectionstring}';
var registry = Registry.fromConnectionString(connectionString);
var client = Client.fromConnectionString(connectionString);
var deviceToReboot = 'myDeviceId';
```

Adicione a seguinte função para invocar o método do dispositivo para reiniciar o dispositivo de destino:

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.");  
        }
    });
};

Adicione a seguinte função para consultar o dispositivo e obter a hora da última reinicialização:

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

Adicione o seguinte código para chamar as funções que dispararão o método direto de reinicialização e consultarão a hora da última reinicialização:
```
startRebootDevice();
setInterval(queryTwinLastReboot, 2000);
```
Salve e feche o arquivo dmpatterns_getstarted_service.js.

Executar os aplicativos

Agora você está pronto para executar os aplicativos.

No prompt de comando da pasta managed-device, execute o seguinte comando para começar a escutar o método direto de reinicialização.
```
node dmpatterns_getstarted_device.js
```
No prompt de comando da pasta trigger-reboot-on-device, execute o seguinte comando para disparar a reinicialização e a consulta remotas para o dispositivo gêmeo localizar o tempo de reinicialização mais recente.
```
node dmpatterns_getstarted_service.js
```
Você vê a resposta do dispositivo ao método direto de reinicialização e o status da reinicialização no console.

O seguinte item mostra a resposta do dispositivo ao método direto de reinicialização enviado pelo serviço:

O seguinte item mostra o serviço disparando a reinicialização e sondando o dispositivo gêmeo para obter o último horário de reinicialização:

Personalizar e estender as ações de gerenciamento do dispositivo

As soluções de IoT podem expandir o conjunto definido de padrões de gerenciamento do dispositivo ou habilitar padrões personalizados usando o dispositivo gêmeo e os primitivos do método da nuvem para o dispositivo. Outros exemplos de ações de gerenciamento do dispositivo incluem a redefinição de fábrica, atualização do firmware, atualização do software, gerenciamento de energia, gerenciamento da rede e da conectividade, e criptografia dos dados.

Janelas de manutenção do dispositivo

Normalmente, você pode configurar os dispositivos para executar ações em um horário que minimiza as interrupções e a inatividade. As janelas de manutenção do dispositivo são um padrão usado para definir a hora em que um dispositivo deve atualizar sua configuração. As soluções de back-end podem usar as propriedades desejadas do dispositivo gêmeo para definir e ativar uma política no dispositivo que permite uma janela de manutenção. Quando um dispositivo recebe a política da janela de manutenção, ele pode usar a propriedade relatada do dispositivo gêmeo para informar o status da política. O aplicativo de back-end pode usar as consultas do dispositivo gêmeo para atestar a conformidade dos dispositivos e cada política.

Próximas etapas

Neste artigo, você usou um método direto para disparar uma reinicialização remota em um dispositivo. Você usou as propriedades relatadas para relatar a hora da última reinicialização do dispositivo e consultou o dispositivo gêmeo para descobrir a hora da última reinicialização do dispositivo na nuvem.

Para continuar a usar o Hub IoT e os padrões de gerenciamento de dispositivos, como a atualização baseada em imagem de ponta a ponta no artigo de Atualização de dispositivo para o Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B+.

Para saber como estender a sua solução de IoT e agendar chamadas de método em vários dispositivos, consulte Agendar e difundir trabalhos.

Compartilhar via