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

  • Artigo

os dispositivos duplos são documentos JSON que armazenam informações de estado dos dispositivos, incluindo metadados, configurações e condições. O Hub IoT persiste um gêmeo de dispositivo para cada dispositivo que se conecta a ele.

Nota

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

Use gêmeos de dispositivo para:

  • Armazene metadados do dispositivo a partir do back-end da solução.

  • Relate informações de estado atual, como recursos e condições disponíveis, por exemplo, o método de conectividade usado, do aplicativo do dispositivo.

  • Sincronize o estado de fluxos de trabalho de longa execução, como atualizações de firmware e configuração, entre um aplicativo de dispositivo e um aplicativo back-end.

  • Consulte os metadados, a configuração ou o estado do dispositivo.

Os gêmeos de dispositivo são projetados para sincronização e para consultar configurações e condições do dispositivo. Para obter mais informações sobre gêmeos de dispositivo, incluindo quando usar gêmeos de dispositivo, consulte Compreender gêmeos de dispositivo.

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

  • Etiquetas. Metadados do dispositivo acessíveis apenas pelo back-end da solução.

  • Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo do dispositivo.

  • Propriedades relatadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

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

A ilustração a seguir mostra a organização de gêmeos do dispositivo:

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

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

Este artigo mostra-lhe como:

  • Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no gêmeo do dispositivo.

  • Consulte dispositivos a partir do seu aplicativo back-end usando filtros nas tags e propriedades criadas anteriormente.

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

  • AddTagsAndQuery.js: um aplicativo back-end que adiciona tags e consulta gêmeos de dispositivo.

  • TwinSimulatedDevice.js: um aplicativo de dispositivo simulado que se conecta ao seu hub IoT e relata sua condição de conectividade.

Nota

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

Pré-requisitos

Para concluir este artigo, precisa de:

  • Um hub IoT. Crie um com a CLI ou o portal do Azure.

  • Um dispositivo registado. 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 neste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço 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 propriedades relatadas que foram atualizadas adequadamente. Seu serviço precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa da permissão de 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 permissões de conexão de serviço e de leitura do Registro e obtenha uma cadeia de conexão para essa política, siga estas etapas:

  1. No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o hub na lista de recursos.

  2. No painel esquerdo do hub, selecione Políticas de acesso compartilhado.

  3. No menu superior acima da lista de políticas, selecione Adicionar política de acesso à política compartilhada.

  4. No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para sua política, como serviceAndRegistryRead. Em Permissões, selecione Leitura do Registro e Conexão de Serviço e, em seguida, selecione Adicionar.

    Captura de tela que mostra como adicionar uma nova política de acesso compartilhado.

  5. Selecione sua nova política na lista de políticas.

  6. Selecione o ícone de cópia para a cadeia de conexão principal e salve o valor.

    Captura de tela que mostra como recuperar a cadeia de conexão.

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

Criar um aplicativo de dispositivo que atualize as propriedades relatadas

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

  1. Crie uma nova pasta vazia chamada reportconnectivity. Na pasta reportconnectivity, crie um novo arquivo de package.json usando o seguinte comando no prompt de comando. O --yes parâmetro aceita todos os padrões.

    npm init --yes

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

  3. Usando um editor de texto, crie um novo arquivo de ReportConnectivity.js na pasta reportconnectivity .

  4. Adicione o seguinte código 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 interagir com gêmeos de dispositivo a partir do dispositivo. O código anterior, depois de inicializar o objeto Client , recupera o gêmeo de dispositivo para myDeviceId e atualiza sua propriedade relatada com as informações de conectividade.

  5. Executar o aplicativo de dispositivo

        node ReportConnectivity.js

    Deverá ver a mensagem twin state reported.

  6. Agora que o dispositivo relatou suas informações de conectividade, ele deve aparecer em ambas as consultas. Volte para a pasta addtagsandqueryapp e execute as consultas novamente:

        node AddTagsAndQuery.js

    Desta vez , myDeviceId deve aparecer em ambos os resultados da consulta.

    Mostrar myDeviceId em ambos os resultados da consulta

Criar um aplicativo de serviço que atualize as propriedades desejadas e consulte gêmeos

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

  1. Crie uma nova pasta vazia chamada addtagsandqueryapp. Na pasta addtagsandqueryapp, crie um novo arquivo package.json usando o seguinte comando no prompt de comando. O --yes parâmetro aceita todos os padrões.

    npm init --yes

  2. No prompt de comando na pasta addtagsandqueryapp , execute o seguinte comando para instalar o pacote azure-iothub :

    npm install azure-iothub --save

  3. Usando um editor de texto, crie um novo arquivo AddTagsAndQuery.js na pasta addtagsandqueryapp .

  4. Adicione o seguinte código ao arquivo AddTagsAndQuery.js . Substitua {iot hub connection string} pela cadeia de conexão do Hub IoT copiada 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 primeiro inicializa o objeto Registry , em seguida, recupera o dispositivo gêmeo para myDeviceId e, finalmente, atualiza suas tags com as informações de localização desejadas.

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

  5. Adicione o seguinte código no final do 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 apenas os gêmeos de dispositivos localizados na planta Redmond43 , e a segunda refina a consulta para selecionar apenas os dispositivos que também estão conectados através da rede celular.

    Quando o código cria o objeto de consulta , ele especifica o número máximo de documentos retornados no segundo parâmetro. O objeto de consulta contém uma propriedade booleana 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 resultados que não são gêmeos de dispositivo, por exemplo, os resultados de consultas de agregação.

  6. Execute o aplicativo com:

        node AddTagsAndQuery.js

    Você deve ver um dispositivo nos resultados da consulta solicitando todos os dispositivos localizados em Redmond43 e nenhum para a consulta que restringe os resultados a dispositivos que usam uma rede celular.

    Ver um dispositivo nos resultados da consulta

Neste artigo, irá:

  • Metadados de dispositivo adicionados como tags de um aplicativo back-end
  • Informações de conectividade do dispositivo relatadas no gêmeo do dispositivo
  • Consultado as informações do gêmeo do dispositivo, usando a linguagem de consulta do Hub IoT semelhante ao SQL

Próximos passos

Para saber como: