Introdução ao gerenciamento de dispositivos (CLI do Azure)

Artigo
03/17/2023

Os aplicativos de back-end podem usar primitivos do Hub IoT do Azure, como dispositivos gêmeos e métodos diretos, para iniciar e monitorar remotamente as ações de gerenciamento de dispositivo nos dispositivos. Este artigo mostra como a CLI do Azure e um dispositivo podem trabalhar juntos para invocar um método direto para um dispositivo usando Hub IoT.

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 sua solução.

Use um método direto para iniciar as ações de gerenciamento do dispositivo (como a reinicialização, redefinição de fábrica e atualização do firmware) em uma sessão da CLI do Azure. O dispositivo é responsável por:

Lidar com a solicitação do método enviada a partir do Hub IoT.
Iniciar a ação específica do dispositivo correspondente no dispositivo.
Fornecimento de atualizações de status por meio das propriedades relatadas para o Hub IoT.

Você pode usar a CLI do Azure para executar consultas do dispositivo gêmeo para relatar o progresso de suas ações de gerenciamento do dispositivo. Para obter mais informações sobre como usar métodos diretos, confira Diretrizes de comunicação entre a nuvem e o dispositivo.

Este artigo mostra como criar duas sessões da CLI do Azure:

Uma sessão que cria um dispositivo simulado. O dispositivo simulado é configurado para retornar um código de status e uma carga JSON quando qualquer método direto é invocado.
Uma sessão que invoca um método direto no dispositivo simulado criado na outra sessão.

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 na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.
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).

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 duas sessões 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 duas sessões da CLI

Em seguida, você precisa preparar duas sessões da CLI do Azure. Se estiver usando o Cloud Shell, você executará essas sessões em guias separadas do Cloud Shell. Se estiver usando um cliente CLI local, executará instâncias separadas da CLI. Use as sessões separadas da CLI para as seguintes tarefas:

A primeira sessão simula um dispositivo IoT que se comunica com o hub IoT.
A segunda sessão invoca um método direto do dispositivo simulado usando o hub IoT.

Observação

A CLI do Azure exige que você esteja conectado à sua conta do Azure. Se você estiver usando o Cloud Shell, será conectado automaticamente à sua conta do Azure. Se você estiver usando um cliente da CLI local, faça logon em cada sessão da CLI. Toda a comunicação entre a sessão shell da CLI do Azure e o 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 fazer logon com a CLI do Azure, confira Entrar com a CLI do Azure.

Na primeira 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.
Abra a segunda sessão da CLI. Se você estiver usando o Cloud Shell em um navegador, selecione o ícone Abrir nova sessão na barra de ferramentas da primeira sessão da CLI. Se estiver usando a CLI localmente, abra uma segunda instância da CLI.

Criar e simular um dispositivo

Nesta seção, você cria uma identidade de dispositivo para o hub IoT na primeira sessão da CLI e simula um dispositivo usando essa identidade do dispositivo. O dispositivo simulado responde aos métodos diretos que você invoca na segunda sessão da CLI.

Para criar e iniciar um dispositivo simulado:

Na primeira 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 dispositivo simulado.

{DeviceName}. O nome do dispositivo simulado.

{HubName}. O nome de seu hub IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
Na primeira sessão da CLI, execute o comando az iot device simulate, substituindo os espaços reservados a seguir por seus valores correspondentes. Esse comando simula um dispositivo usando a identidade do dispositivo que você criou na etapa anterior. O dispositivo simulado é configurado para retornar um código de status e uma carga sempre que um método direto é invocado.

{DeviceName}. O nome do dispositivo simulado.

{HubName}. O nome de seu hub IoT.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --method-response-code 201 \
                       --method-response-payload '{"result":"Direct method successful"}'
```
Dica

Por padrão, o comando az iot device simulate envia 100 mensagens de dispositivo para nuvem com um intervalo de 3 segundos entre mensagens. A simulação termina depois que todas as mensagens são enviadas. Se quiser que a simulação seja executada por mais tempo, você poderá usar o parâmetro --msg-count para especificar mais mensagens ou o parâmetro --msg-interval para especificar um intervalo mais longo entre as mensagens. Você também pode executar o comando novamente para reiniciar o dispositivo simulado.

Invocar um método direto

Nesta seção, você usa a segunda sessão da CLI para invocar um método direto no dispositivo simulado em execução na primeira sessão da CLI.

Confirme se o dispositivo simulado está em execução. Caso contrário, reinicie-o executando o comando az iot device simulate novamente em Criar e simular um dispositivo.
Na segunda sessão da CLI, execute o comando az iot hub invoke-device-method, substituindo os espaços reservados a seguir por seus valores correspondentes. Neste exemplo, não há um método preexistente para o dispositivo. O comando chama um nome de método de exemplo no dispositivo simulado. O método fornece um código de status e conteúdo em sua resposta.

{DeviceName}. O nome do dispositivo simulado.

{HubName}. O nome de seu hub IoT.

{MethodName}. O nome do método direto. O dispositivo simulado não tem um método pré-existente, portanto, você pode escolher o nome que quiser para este comando.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName}
```
Na primeira sessão da CLI, confirme se a saída mostra a chamada da invocação do método. Na captura de tela a seguir, usamos SampleDevice e SampleMethod para os espaços reservados {DeviceName} e {MethodName}respectivamente, no comando az iot hub invoke-device-method da CLI.
Na segunda sessão da CLI, confirme se a saída mostra o código de status e o conteúdo recebidos do método invocado.

Invocar um método direto com um conteúdo

Nesta seção, você usa a segunda sessão da CLI para invocar um método direto e fornecer um conteúdo para o dispositivo simulado em execução na primeira sessão da CLI.

Confirme se o dispositivo simulado está em execução. Caso contrário, reinicie-o executando o comando az iot device simulate novamente em Criar e simular um dispositivo.
Na segunda sessão da CLI, execute o comando az iot hub invoke-device-method, substituindo os espaços reservados a seguir por seus valores correspondentes. Neste exemplo, não há um método preexistente para o dispositivo. O comando chama um nome de método de exemplo no dispositivo simulado e fornece um conteúdo para esse método. O método fornece um código de status e conteúdo em sua resposta.

{DeviceName}. O nome do dispositivo simulado.

{HubName}. O nome de seu hub IoT.

{MethodName}. O nome do método direto. O dispositivo simulado não tem um método pré-existente, portanto, você pode escolher o nome que quiser para este comando.
```
az iot hub invoke-device-method --device-id {DeviceName} --hub-name {HubName} \
                                --method-name {MethodName} \
                                --method-payload '{ "SamplePayload": "PayloadValue" }'
```
Na primeira sessão da CLI, confirme se a saída mostra a chamada da invocação do método. Na captura de tela a seguir, usamos SampleDevice e SampleMethod para os espaços reservados {DeviceName} e {MethodName}respectivamente, no comando az iot hub invoke-device-method da CLI.
Na segunda sessão da CLI, confirme se a saída mostra o código de status e o conteúdo recebidos do método invocado.

Próximas etapas

Para saber como usar a CLI do Azure para estender a sua solução IoT e agendar invocações de método 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+.

Compartilhar via