Introdução à identidade do módulo Hub IoT e ao módulo duplo (Node.js)

Artigo
03/18/2023

As identidades de módulo e os módulos duplos assemelham-se à identidade do dispositivo e ao dispositivo duplo do Hub IoT do Azure, exceto no facto de oferecerem melhor granularidade. Embora Hub IoT do Azure identidade do dispositivo e o dispositivo duplo permitam que a aplicação de back-end configure um dispositivo e forneça visibilidade sobre as condições do dispositivo, uma identidade do módulo e o módulo duplo fornecem estas capacidades para componentes individuais de um dispositivo. Em dispositivos compatíveis com vários componentes, como dispositivos de sistema operativo ou dispositivos de firmware, permite configuração e condições isoladas para cada componente.

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão do Hub IoT. Para obter mais informações sobre os escalões de Hub IoT básico e standard/gratuito, consulte Escolher o escalão de Hub IoT certo para a sua solução.

No final deste artigo, tem duas aplicações Node.js:

CreateIdentities: cria uma identidade de dispositivo, uma identidade de módulo e chaves de segurança associadas para ligar os clientes do dispositivo e do módulo.
UpdateModuleTwinReportedProperties: envia o módulo duplo atualizado, as propriedades comunicadas para o Hub IoT.

Nota

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

Pré-requisitos

Um hub IoT. Crie uma com a CLI ou a portal do Azure.
Node.js versão 10.0.x ou posterior. Preparar o ambiente de desenvolvimento descreve como instalar Node.js para este artigo no Windows ou Linux.

Autenticação de módulos

Pode utilizar chaves simétricas ou certificados X.509 para autenticar identidades de módulos. Para a autenticação de certificado X.509, o certificado do módulo tem de ter o respetivo nome comum (CN) formatado como CN=<deviceid>/<moduleid>. Por exemplo:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Obter a cadeia de ligação do hub IoT

Neste artigo, vai criar um serviço de back-end que adiciona um dispositivo no registo de identidade e, em seguida, adiciona um módulo a esse dispositivo. O seu serviço requer a permissão de escrita do registo . Por predefinição, cada hub IoT é criado com uma política de acesso partilhado denominada registryReadWrite que concede esta permissão.

Para obter a cadeia de ligação Hub IoT para a política registryReadWrite, siga estes passos:

Na 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.
No painel esquerdo do hub, selecione Políticas de acesso partilhado.
Na lista de políticas, selecione a política registryReadWrite .
Copie a cadeia de ligação Primária e guarde o valor.

Para obter mais informações sobre Hub IoT permissões e políticas de acesso partilhado, veja Controlo de acesso e permissões.

Criar uma identidade de dispositivo e uma identidade de módulo no Hub IoT

Nesta secção, vai criar uma aplicação Node.js que cria uma identidade de dispositivo e uma identidade de módulo no registo de identidades no seu hub IoT. Um dispositivo ou módulo não consegue ligar-se ao hub IoT, a menos que tenha uma entrada no registo de identidade. Para obter mais informações, veja Compreender o registo de identidades no seu hub IoT. Ao executar esta aplicação de consola, será gerado um ID e uma chave exclusivos para o dispositivo e o módulo. O ID e a chave são sensíveis às maiúsculas e minúsculas. O dispositivo e o módulo utilizam estes valores para se identificarem quando enviam mensagens do dispositivo para cloud para o Hub IoT.

Crie um diretório para guardar o código.
Dentro desse diretório, execute primeiro npm init -y para criar um package.json vazio com predefinições. Este é o ficheiro de projeto do seu código.
Execute a instalação npm -S azure-iothub@modules-preview para instalar o SDK do serviço no subdiretório node_modules .

Nota

O nome do subdiretório node_modules utiliza a palavra módulo para significar "uma biblioteca de nós". O termo aqui não tem nada a ver com Hub IoT módulos.

Crie o seguinte ficheiro .js no seu diretório. Chame-lhe add.js. Copie e cole a cadeia de ligação do hub e o nome do hub.

var Registry = require('azure-iothub').Registry;
var uuid = require('uuid');
// Copy/paste your connection string and hub name here
var serviceConnectionString = '<hub connection string from portal>';
var hubName = '<hub name>.azure-devices.net';
// Create an instance of the IoTHub registry
var registry = Registry.fromConnectionString(serviceConnectionString);
// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice';
var moduleId = 'myFirstModule';
// Create your device as a SAS authentication device
var primaryKey = new Buffer(uuid.v4()).toString('base64');
var secondaryKey = new Buffer(uuid.v4()).toString('base64');
var deviceDescription = {
  deviceId: deviceId,
  status: 'enabled',
  authentication: {
    type: 'sas',
    symmetricKey: {
      primaryKey: primaryKey,
      secondaryKey: secondaryKey
    }
  }
};

// First, create a device identity
registry.create(deviceDescription, function(err) {
  if (err) {
    console.log('Error creating device identity: ' + err);
    process.exit(1);
  }
  console.log('device connection string = "HostName=' + hubName + ';DeviceId=' + deviceId + ';SharedAccessKey=' + primaryKey + '"');

  // Then add a module to that device
  registry.addModule({ deviceId: deviceId, moduleId: moduleId }, function(err) {
    if (err) {
      console.log('Error creating module identity: ' + err);
      process.exit(1);
    }

    // Finally, retrieve the module details from the hub so we can construct the connection string
    registry.getModule(deviceId, moduleId, function(err, foundModule) {
      if (err) {
        console.log('Error getting module back from hub: ' + err);
        process.exit(1);
      }
      console.log('module connection string = "HostName=' + hubName + ';DeviceId=' + foundModule.deviceId + ';ModuleId='+foundModule.moduleId+';SharedAccessKey=' + foundModule.authentication.symmetricKey.primaryKey + '"');
      process.exit(0);
    });
  });
});

Esta aplicação cria uma identidade de dispositivo com o ID myFirstDevice e uma identidade de módulo com o ID myFirstModule no dispositivo myFirstDevice. (Se esse ID do módulo já existir no registo de identidade, o código simplesmente obtém as informações do módulo existente.) Em seguida, a aplicação apresenta a chave primária dessa identidade. Esta chave vai ser utilizada na aplicação do módulo simulado para ligar ao seu hub IoT.

Execute-o com add.js de nós. Irá fornecer-lhe uma cadeia de ligação para a identidade do dispositivo e outra para a identidade do módulo.

Nota

O registo de identidade do Hub IoT apenas armazena identidades de dispositivos e módulos para permitir um acesso seguro ao hub IoT. O registo de identidades armazena os IDs de dispositivo e as chaves para utilizar como credenciais de segurança. O registo de identidades também armazena um sinalizador ativado/desativado para cada dispositivo que pode utilizar para desativar o acesso a esse dispositivo. Se a sua aplicação tiver de armazenar outros metadados específicos do dispositivo, deverá utilizar um armazenamento específico da aplicação. Não existe nenhum sinalizador ativado/desativado para identidades de módulo. Para obter mais informações, veja Understand the identity registry in your Hub IoT (Compreender o registo de identidades no seu Hub IoT) no guia para programadores do Hub IoT.

Atualizar o módulo duplo com o SDK do dispositivo Node.js

Nesta secção, vai criar uma aplicação Node.js no seu dispositivo simulado que atualiza as propriedades reportadas do módulo duplo.

Obtenha a cadeia de ligação do módulo. Inicie sessão no portal do Azure. Navegue para a sua Hub IoT e selecione Dispositivos IoT. Localize myFirstDevice, abra-o e verá que myFirstModule foi criado com êxito. Copie a cadeia de ligação do módulo. É necessária para o próximo passo.
À semelhança do que fez na secção anterior, crie um diretório para o código do dispositivo e utilize o NPM para inicializá-lo e instalar o SDK do dispositivo (npm install -S azure-iot-device-amqp@modules-preview).

Nota

O comando de instalação do npm pode parecer lento. Seja paciente; Está a extrair muitos códigos do repositório de pacotes.

Nota

Se vir um erro a indicar npm ERR! erro de registo ao analisar json, isto é seguro de ignorar. Se vir um erro a indicar npm ERR! erro de registo ao analisar json, isto é seguro de ignorar.

Crie um ficheiro chamado twin.js. Copie e cole a cadeia de identidade do módulo.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = '<insert module connection string here>';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 72,
        humidity: 17
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });
  });
});

Agora, execute-o com o nó de comando twin.js.

F:\temp\module_twin>node twin.js

Em seguida, verá:

client opened
twin contents:
{ reported: { update: [Function: update], '$version': 1 },
  desired: { '$version': 1 } }
new desired properties received:
{"$version":1}
twin state reported

Passos seguintes

Para continuar a introdução ao Hub IoT e explorar outros cenários de IoT, veja:

Partilhar via

Introdução à identidade do módulo Hub IoT e ao módulo duplo (Node.js)

Pré-requisitos

Autenticação de módulos

Obter a cadeia de ligação do hub IoT

Criar uma identidade de dispositivo e uma identidade de módulo no Hub IoT

Atualizar o módulo duplo com o SDK do dispositivo Node.js

Passos seguintes

Recursos adicionais