Introdução aos dispositivos gêmeos (Node.js)

Artigo
03/19/2023

Dispositivos gêmeos são documentos JSON que armazenam informações do estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT persiste um dispositivo gêmeo para cada dispositivo que você conecta a ele.

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 os dispositivos gêmeos para:

Armazene os metadados de dispositivo de seu back-end da solução.
Relate informações de estado atual, como funcionalidades disponíveis e condições (por exemplo, o método conectividade usado) do aplicativo do dispositivo.
Sincronize o estado dos fluxos de trabalho de longa duração (como atualizações de firmware e de configuração) entre um aplicativo de dispositivo e um aplicativo de back-end.
Consultar os metadados, a configuração ou o estado do seu dispositivo.

Dispositivos gêmeos são projetados para sincronização e para consultar condições e configurações de dispositivos. Para obter mais informações sobre dispositivos gêmeos e quando usá-los, confira Noções básicas sobre dispositivos gêmeos.

Os hubs IoT armazenam dispositivos gêmeos, que contêm os seguintes elementos:

Marcas. Metadados do dispositivo acessíveis apenas por meio do back-end da solução.
Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo de dispositivo.
Propriedades reportadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

Marcas e propriedades não podem conter matrizes, mas podem conter objetos aninhados.

A ilustração a seguir mostra a organização de um dispositivo gêmeo:

Captura de tela de um diagrama de conceito de dispositivo gêmeo.

Além disso, o back-end da solução pode consultar dispositivos gêmeos com base em todos os dados acima. Para obter mais informações sobre dispositivos gêmeos, consulte Noções básicas de dispositivos gêmeos. Para obter mais informações sobre a consulta, consulte Linguagem de consulta do Hub IoT.

Este artigo mostra como:

Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo.
Consulte dispositivos por meio do aplicativo de back-end usando filtros nas marcações e propriedades criadas anteriormente.

Neste artigo, você vai criar dois aplicativos de console Node.js:

AddTagsAndQuery.js: um aplicativo de back-end que adiciona marcas e faz consultas a dispositivos gêmeos.
TwinSimulatedDevice.js: um aplicativo de dispositivo simulado que se conecta ao hub IoT e relata sua condição de conectividade.

Observação

Consulte os SDKs da IoT do Azure para obter mais informações sobre as ferramentas do SDK disponíveis para compilar aplicativos de dispositivo e back-end.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado. Registre um no portal do Azure.
Node.js versão 10.0.x ou posterior.
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).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que adiciona as propriedades desejadas a um dispositivo gêmeo e, em seguida, consulta o registro de identidade para localizar todos os dispositivos com as propriedades relatadas que foram atualizadas de acordo. O seu serviço precisa da permissão conexão de serviço para modificar as propriedades desejadas de um dispositivo gêmeo e precisa da permissão leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma.

Para criar uma política de acesso compartilhado que conceda as permissões conexão de serviço e leitura de registro e obter uma cadeia de conexão para essa política, 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, selecione Políticas de acesso compartilhado.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso compartilhado.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para a política, como serviceAndRegistryRead. Em Permissões, selecione Leitura de Registro e Conexão de Serviço e selecione Adicionar.
Selecione a sua nova política na lista de políticas.
Selecione o ícone de cópia da 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 dispositivo que atualiza as propriedades relatadas

Nesta seção, você cria um aplicativo de console do Node.js que se conecta ao seu hub como myDeviceId e depois atualiza as propriedades relatadas do dispositivo gêmeo para confirmar que ele está conectado usando uma rede celular.

Crie uma nova pasta vazia denominada reportconnectivity. Na pasta reportconnectivity, crie um novo arquivo package.json usando o comando a seguir no prompt de comando. O parâmetro --yes aceita todos os padrões.
```
npm init --yes
```
No prompt de comando, na pasta reportconnectivity, execute o seguinte comando para instalar os pacotes azure-iot-device e azure-iot-device-mqtt:
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
Usando um editor de texto, crie um novo arquivo ReportConnectivity.js na pasta reportconnectivity.

Adicione o código a seguir ao arquivo ReportConnectivity.js. Substitua {device connection string} pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:

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

O objeto Client expõe todos os métodos necessários para você interagir com dispositivos gêmeos a partir do dispositivo. O código anterior, depois de inicializar o objeto Client, recupera o dispositivo gêmeo para myDeviceId e atualiza suas propriedades reportadas com as informações de conectividade.

Executar o aplicativo do dispositivo
```
    node ReportConnectivity.js
```
Você deve ver a mensagem twin state reported.
Agora que o dispositivo divulgou suas informações de conectividade, ele deve aparecer em ambas as consultas. Acesse novamente a pasta addtagsandqueryapp e execute as consultas novamente:
```
    node AddTagsAndQuery.js
```
Desta vez, myDeviceId deve aparecer em ambos os resultados da consulta.

Criar um aplicativo de serviço que atualiza as propriedades desejadas e consulta gêmeos

Nesta seção, você cria um aplicativo de console do Node.js que adiciona metadados de local ao dispositivo gêmeo associado a myDeviceId. O aplicativo consulta no hub IoT se há dispositivos localizados nos EUA e, em seguida, consulta dispositivos que relatam a uma conexão de rede de celular.

Crie uma nova pasta vazia denominada addtagsandqueryapp. Na pasta addtagsandqueryapp, crie um novo arquivo package.json usando o comando a seguir no prompt de comando. O parâmetro --yes aceita todos os padrões.
```
npm init --yes
```
No prompt de comando, na pasta addtagsandqueryapp, execute o seguinte comando para instalar o pacote azure-iothub:
```
npm install azure-iothub --save
```
Usando um editor de texto, crie um novo arquivo AddTagsAndQuery.js na pasta addtagsandqueryapp.

Adicione o código a seguir ao arquivo AddTagsAndQuery.js. Substitua {iot hub connection string} pela cadeia de conexão do Hub IoT que você copiou em Obter a cadeia de conexão do hub IoT.

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

O objeto Registry expõe todos os métodos necessários para interagir com gêmeos de dispositivo do serviço. O código anterior inicializa primeiro o objeto Registry, depois, recupera o dispositivo gêmeo para myDeviceId e finalmente atualiza as marcas com as informações do local desejado.

Depois de atualizar as marcas, ele chama a função queryTwins.

Adicione o seguinte código ao final de AddTagsAndQuery.js para implementar a função 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(','));
             }
         });
     };

O código anterior executa duas consultas: a primeira seleciona somente os dispositivos gêmeos de dispositivos localizados na fábrica de Redmond43, e o segundo aperfeiçoa a consulta para selecionar somente os dispositivos que também estão conectados por meio de rede celular.

Quando o código cria o objeto query, ele especifica o número máximo de documentos retornados no segundo parâmetro. O objeto query contém uma propriedade booliana hasMoreResults que você pode usar para invocar os métodos nextAsTwin várias vezes para recuperar todos os resultados. Um método chamado next está disponível para os resultados que não são dispositivos gêmeos, por exemplo, os resultados de consultas de agregação.

Execute o aplicativo com:
```
    node AddTagsAndQuery.js
```
Você deve ver um dispositivo nos resultados da consulta que pergunta sobre todos os dispositivos localizados em Redmond43, e nenhum para a consulta que restringe os resultados para dispositivos que usam uma rede de celular.

Neste artigo você:

Adicionou metadados do dispositivo como marcas de um aplicativo de back-end
Relatou informações de conectividade do dispositivo no dispositivo gêmeo
Consultou as informações do dispositivo gêmeo usando a linguagem de consulta do Hub IoT semelhante a SQL

Próximas etapas

Para saber como:

Enviar telemetria de dispositivos, consulte Início Rápido: enviar telemetria de um dispositivo IoT Plug and Play para o Hub IoT do Azure
Configurar dispositivos usando as propriedades desejadas do dispositivo gêmeo, consulte Tutorial: Configurar seus dispositivos de um serviço de back-end
Controlar dispositivos interativamente, como ativar um ventilador de um aplicativo controlado pelo usuário, consulte Início Rápido: controlar um dispositivo conectado a um hub IoT