Introdução às identidades do módulo do Hub IoT e aos módulos gêmeos usando a CLI do Azure

Artigo
03/20/2023

As identidades do módulo e os módulos gêmeos são semelhantes às identidades do dispositivo e aos dispositivos gêmeos do Hub IoT do Azure, mas fornecem melhor granularidade. Assim como as identidades do dispositivo e os dispositivos gêmeos do Hub IoT do Azure permitem que o aplicativo de back-end configure um dispositivo e forneça visibilidade às condições do dispositivo, as identidades do módulo e os módulos gêmeos fornecem essas funcionalidades para componentes individuais de um dispositivo. Em dispositivos compatíveis com vários componentes, como dispositivos de sistema operacional ou dispositivos de firmware, as identidades do módulo e os módulos gêmeos permitem configuração e condições isoladas para cada componente.

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.

Este artigo mostra como criar uma sessão da CLI do Azure na qual você:

Cria uma identidade do dispositivo e crie uma identidade do módulo para esse dispositivo.
Atualiza um conjunto de propriedades desejadas para o módulo gêmeo associado à identidade do módulo.

Pré-requisitos

CLI do Azure. Você também pode executar os comandos deste artigo usando o Azure Cloud Shell, um shell da CLI interativa executado em seu navegador ou em um aplicativo, como Terminal do Windows. Se você usar o Cloud Shell, não precisará instalar nada. Se preferir usar a CLI localmente, este artigo requer a CLI do Azure versão 2.36 ou posterior. Execute az --version para encontrar a versão. Para instalar ou atualizar a CLI do Azure localmente, confira Instalar a CLI do Azure.
Um hub IoT. Crie um com a CLI ou o portal do Azure.
Verifique se a porta 8883 está aberta no firewall. Os exemplos desse artigo usam 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).

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 nome comum (CN) formatado como CN=<deviceid>/<moduleid>. Por exemplo:

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

Preparar o Cloud Shell

Se você quiser usar o Cloud Shell do Azure, primeiro inicie-o e configure-o. Se você usar a CLI localmente, pule para a seção Preparar a sessão da CLI.

Selecione o ícone Cloud Shell no cabeçalho da página no portal do Azure.

Observação

Se esta for a primeira vez que você usa o Cloud Shell, ele solicitará que você crie o armazenamento, que é necessário para usar o Cloud Shell. Selecione uma assinatura para criar uma conta de armazenamento e um compartilhamento de Arquivos do Microsoft Azure.
Use o seletor de ambiente na barra de ferramentas do Cloud Shell para selecionar seu ambiente de CLI preferido. Este artigo usa o ambiente de Bash. Você também pode usar o ambiente do PowerShell.

Observação

Alguns comandos exigem sintaxe ou formatação diferentes nos ambientes Bash e PowerShell. Para obter mais informações, consulte Dicas para usar a CLI do Azure com êxito.

Preparar uma sessão da CLI

Em seguida, você precisa preparar uma sessão da CLI do Azure. Se você estiver usando o Cloud Shell, execute a sessão em uma guia do Cloud Shell. Se estiver usando um cliente da CLI local, execute a sessão em uma instância da CLI.

Se você estiver usando o Cloud Shell, pule para a próxima etapa. Caso contrário, execute o comando az login na sessão da CLI para entrar em sua conta do Azure.

Se você estiver usando o Cloud Shell, será conectado automaticamente à sua conta do Azure. Toda a comunicação entre a sessão da CLI do Azure e do Hub IoT é autenticada e criptografada. Como resultado, este artigo não precisa da autenticação extra que você usaria com um dispositivo real, como uma cadeia de conexão. Para obter mais informações sobre como entrar com a CLI do Azure, confira Entrar com a CLI do Azure.
```
az login
```
Na sessão da CLI, execute o comando az extension add. O comando adiciona a extensão IoT do Microsoft Azure da CLI do Azure ao shell da CLI. A Extensão de IoT adiciona comandos específicos do Hub IoT, do IoT Edge e do DPS (Serviço de Provisionamento de Dispositivos no Hub IoT) à CLI do Azure. Depois de instalar a extensão, você não precisará instalá-la novamente em nenhuma sessão do Cloud Shell.
```
az extension add --name azure-iot
```
Observação

Este artigo usa a versão mais recente da extensão de IoT do Azure, chamada azure-iot. A versão herdada chama-se azure-cli-iot-ext. Você deve ter apenas uma versão instalada por vez. Use o comando az extension list para validar quais extensões estão instaladas.

Use az extension remove --name azure-cli-iot-ext para remover a versão herdada da extensão.

Use az extension add --name azure-iot para adicionar a nova versão da extensão.

Para ver quais extensões você tem instaladas, use az extension list.

Criar uma identidade do dispositivo e uma identidade do módulo

Nessa seção, você cria uma identidade do dispositivo para seu hub IoT na sessão da CLI e, em seguida, cria uma identidade do módulo usando essa identidade do dispositivo. Você pode criar até 50 identidades do módulo em cada identidade do dispositivo.

Para criar uma identidade do dispositivo e uma identidade do módulo:

Na sessão da CLI, execute o comando az iot hub device-identity create, substituindo os espaços reservados a seguir por seus valores correspondentes. Esse comando cria a identidade do dispositivo para o seu módulo.

{DeviceName}. O nome do seu dispositivo.

{HubName}. O nome de seu hub IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
Na sessão da CLI, execute o comando az iot hub module-identity create, substituindo os espaços reservados a seguir por seus valores correspondentes. Esse comando cria a identidade do módulo para o módulo, na identidade do dispositivo que você criou na etapa anterior.

{DeviceName}. O nome do seu dispositivo.

{HubName}. O nome de seu hub IoT.

{ModuleName}. O nome do módulo do seu dispositivo.
```
az iot hub module-identity create --device-id {DeviceName} --hub-name {HubName} \
                                  --module-id {ModuleName}
```

Atualizar o módulo gêmeo

Depois de criar uma identidade de módulo, um módulo gêmeo é implicitamente criado no Hub IoT. Nesta seção, você usa a sessão da CLI para atualizar um conjunto de propriedades desejadas no módulo gêmeo associado à identidade do módulo que você criou na seção anterior.

Na sessão da CLI, execute o comando az iot hub module-twin update, substituindo os espaços reservados a seguir por seus valores correspondentes. Nesse exemplo, estamos atualizando várias propriedades desejadas no módulo gêmeo para a identidade do módulo que criamos na seção anterior.

{DeviceName}. O nome do seu dispositivo.

{HubName}. O nome de seu hub IoT.

{ModuleName}. O nome do módulo do seu dispositivo.
```
az iot hub module-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --module-id {ModuleName} \
                              --desired '{"conditions":{"temperature":{"warning":75, "critical":100}}}'
```

Na sessão da CLI, confirme se a resposta JSON mostra os resultados da operação de atualização. No exemplo de resposta JSON a seguir, usamos SampleDevice e SampleModule para os espaços reservados {DeviceName} e {ModuleName}, respectivamente, no az iot hub module-twin update comando da CLI.

{
  "authenticationType": "sas",
  "capabilities": null,
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Disconnected",
  "deviceEtag": "Mzg0OEN1NzW=",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": "SampleModule",
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
        "$lastUpdatedVersion": 2,
        "conditions": {
          "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
          "$lastUpdatedVersion": 2,
          "temperature": {
            "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
            "$lastUpdatedVersion": 2,
            "critical": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            },
            "warning": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            }
          }
        }
      },
      "$version": 2,
      "conditions": {
        "temperature": {
          "critical": 100,
          "warning": 75
        }
      }
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": null,
  "version": 3,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Próximas etapas

Para saber como usar a CLI do Azure para estender sua solução de IoT e agendar atualizações em dispositivos, confira Agendar e transmitir trabalhos.

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

Share via