Share via

Introdução à identidade de módulo e ao módulo gêmeo do Hub IoT (Node.js)

  • Artigo

As identidades do módulo e os módulos gêmeos são semelhantes à identidade do dispositivo e ao dispositivo gêmeo do Hub IoT do Azure, mas fornecem melhor granularidade. A identidade de dispositivo e o dispositivo gêmeo do Hub IoT do Azure permitem que o aplicativo de back-end configure um dispositivo e forneça visibilidade às condições dele. Uma identidade de módulo e um módulo gêmeo, por sua vez, fornecem essas funcionalidades para componentes individuais de um dispositivo. Em dispositivos habilitados com vários componentes, como dispositivos de sistema operacional ou dispositivos de firmware, isso permite condições e configuração isolada para cada componente.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para saber mais sobre as camadas Básico e Standard/Gratuita do Hub IoT, confira Escolher a camada ideal do Hub IoT para sua solução.

Ao fim deste artigo, você terá dois aplicativos do Node.js:

  • CreateIdentities: cria uma identidade de dispositivo, uma identidade de módulo e chaves de segurança associadas para conectar seus clientes de dispositivo e módulo.

  • UpdateModuleTwinReportedProperties: envia propriedades relatadas atualizadas de módulo gêmeo ao Hub IoT.

Observação

Para obter mais informações sobre as ferramentas do SDK disponíveis para compilar os dispositivos e os aplicativos de back-end, consulte SDKs de Internet das Coisas do Azure.

Pré-requisitos

Autenticação de módulo

Você pode usar chaves simétricas ou certificados X.509 para autenticar identidades de módulo. Para autenticação de certificado X.509, o certificado do módulo deve ter seu CN (nome comum) 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 conexão do hub IoT

Neste artigo, você criará um serviço de back-end que adiciona um dispositivo no registro de identidade e, em seguida, adiciona um módulo a esse dispositivo. Seu serviço requer a permissão de gravação do registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essa permissão.

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

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

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

  3. Na lista de políticas, selecione a política registryReadWrite.

  4. Copie a Cadeia de conexão primária e salve o valor.

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

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 uma identidade do dispositivo e uma identidade do módulo no Hub IoT

Nesta seção, você criará um aplicativo Node.js que cria uma identidade do dispositivo e uma identidade do módulo no registro de identidade no Hub IoT. Um dispositivo ou módulo não pode se conectar ao Hub IoT, a menos que ele tenha uma entrada no Registro de identidade. Para obter mais informações, consulte Entender o registro de identidade no Hub IoT. Quando você executa esse aplicativo de console, ele gera ID e chave exclusivas para o dispositivo e o módulo. A ID e a chave diferenciam maiúsculas de minúsculas. O dispositivo e o módulo usam esses valores para se identificar ao enviar mensagens de dispositivo para nuvem para o Hub IoT.

  1. Crie um diretório para manter o código.

  2. Dentro desse diretório, primeiro execute npm init -y para criar um package.json vazio com os padrões. Esse é o arquivo de projeto do código.

  3. Execute npm install -S azure-iothub@modules-preview para instalar o SDK de serviço no subdiretório node_modules.

    Observação

    O nome do subdiretório node_modules usa o módulo word para significar "uma biblioteca de nós". Este termo não está relacionado com módulos do Hub IoT.

  4. Crie o seguinte arquivo .js no diretório. Chame-o de add.js. Copie e cole a cadeia de conexã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);
    });
  });
});

Esse aplicativo cria uma identidade do dispositivo com a ID myFirstDevice e uma identidade do módulo com a ID myFirstModule no dispositivo myFirstDevice. (Quando essa identidade do módulo já existe no registro de identidade, o código simplesmente recupera as informações do módulo existente.) Em seguida, o aplicativo exibe a chave primária dessa identidade. Você usa essa chave no aplicativo de módulo simulado para se conectar ao Hub IoT.

Execute isso usando o nó add.js. Ele fornecerá uma cadeia de conexão para a identidade do dispositivo e outra para a identidade do módulo.

Observação

O Registro de identidade do Hub IoT armazena apenas as identidades de dispositivo e módulo para habilitar o acesso seguro ao Hub IoT. O registro de identidade armazena IDs de dispositivo e chaves para usar como credenciais de segurança. O registro de identidade também armazena um sinalizador de habilitado/desabilitado para cada dispositivo que você pode usar para desabilitar o acesso ao dispositivo. Se seu aplicativo precisar armazenar outros metadados específicos do dispositivo, ele deverá usar um repositório específico do aplicativo. Não há nenhum sinalizador habilitado/desabilitado para as identidades do módulo. Para obter mais informações, confira Entender o registro de identidade no Hub IoT no guia do desenvolvedor do Hub IoT.

Atualizar o módulo gêmeo usando o SDK do dispositivo Node.js

Nesta seção, você criará um aplicativo Node.js no dispositivo simulado que atualiza as propriedades relatadas do módulo gêmeo.

  1. Obtenha a cadeia de conexão do módulo. Entre no portal do Azure. Navegue até seu Hub IoT e selecione dispositivos IoT. Localize myFirstDevice e abra-o. Você verá que myFirstModule foi criado com êxito. Copie a cadeia de conexão do módulo. Ela será necessária na próxima etapa.

    Detalhes do módulo do Portal do Azure

  2. Semelhante ao que você fez na seção anterior, crie um diretório para o código do seu dispositivo e use o NPM para inicializá-lo e instalar o SDK do dispositivo (npm install -S azure-iot-device-amqp @modules -preview).

    Observação

    O comando npm install pode parecer lento. Seja paciente; ele está extraindo muitos códigos do repositório de pacotes.

    Observação

    Se você visualizar um erro informando npm ERR! erro de registro de análise de json, é seguro ignorar. Se você visualizar um erro informando npm ERR! erro de registro de análise de json, é seguro ignorar.

  3. Crie um arquivo chamado twin.js. Copie e cole a cadeia de caracteres 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');
    });
  });
});

  4. Agora, execute isso usando o comando node twin.js.

    F:\temp\module_twin>node twin.js

    Em seguida, você verá o seguinte:

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

Próximas etapas

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