Agendar e difundir trabalhos (CLI do Azure)

Artigo
03/16/2023

Use o Hub IoT do Azure para agendar e controlar os trabalhos que atualizam milhões de dispositivos. Use trabalhos para:

Atualizar as propriedades desejadas
Marcas de atualização
Chamar métodos diretos

Conceitualmente, um trabalho encapsula uma dessas ações e rastreia o progresso da execução com relação a um conjunto de dispositivos. O conjunto de dispositivos com os quais um trabalho interage é definido por uma consulta de dispositivo gêmeo. Por exemplo, um aplicativo de back-end pode usar um trabalho para invocar um método de reinicialização em 10.000 dispositivos, especificado por uma consulta do dispositivo gêmeo e agendado no futuro. Esse aplicativo pode acompanhar o progresso à medida que cada um desses dispositivos recebe e executa o método de reinicialização.

Saiba mais sobre cada um desses recursos nestes artigos:

Dispositivo gêmeo e propriedades: Introdução aos dispositivos gêmeos e Entender e usar os dispositivos gêmeos no Hub IoT
Métodos direitos: Guia do desenvolvedor no Hub IoT – métodos diretos

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.

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 cria dois trabalhos agendados. O primeiro trabalho invoca um método direto e o segundo trabalho atualiza uma propriedade de dispositivo gêmeo desejada 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 agenda trabalhos para seu dispositivo simulado com 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 trabalhos agendados 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 o 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.

Agendar um trabalho para invocar um método direto

Nesta seção, você agenda um trabalho na 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 job create, 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 agenda um trabalho que chama um nome de método de exemplo no dispositivo simulado, fornecendo um valor nulo para o conteúdo do método. O método fornece um código de status e conteúdo em sua resposta.

{HubName}. O nome de seu hub IoT.

{JobName}. O nome do trabalho agendado. Os nomes de trabalho são exclusivos, portanto, escolha um nome de trabalho diferente sempre que você executar esse comando.

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

{DeviceName}. O nome do dispositivo simulado.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleDeviceMethod \
                      --method-name {MethodName} --method-payload 'null' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Dica

Ao agendar um comando az iot hub job create de trabalho que invoca um método direto, você deve especificar valores para os parâmetros opcionais --method-name e --method-payload. Para métodos diretos que não aceitam uma carga, especifique null para o parâmetro --method-payload.
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 job create da CLI da etapa anterior.

Agendar um trabalho para atualizar as propriedades de um dispositivo gêmeo

Nesta seção, você agenda um trabalho na segunda sessão da CLI para atualizar uma propriedade de dispositivo gêmeo desejada 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 job create, substituindo os espaços reservados a seguir por seus valores correspondentes. Neste exemplo, estamos agendando um trabalho para definir o valor da propriedade BuildingNo de gêmeo desejada como 45 para nosso dispositivo simulado.

{HubName}. O nome de seu hub IoT.

{JobName}. O nome do trabalho agendado. Os nomes de trabalho são exclusivos, portanto, escolha um nome de trabalho diferente sempre que você executar esse comando.

{DeviceName}. O nome do dispositivo simulado.
```
az iot hub job create --hub-name {HubName} --job-id {JobName} \
                      --job-type scheduleUpdateTwin \
                      --twin-patch '{"properties":{"desired": {"BuildingNo": 45}}}' \
                      --query-condition "deviceId = '{DeviceName}'"
```
Na primeira sessão da CLI, confirme se a saída mostra a atualização bem-sucedida para a propriedade de dispositivo gêmeo relatada, indicando que a propriedade de dispositivo gêmeo desejada também foi atualizada.

Próximas etapas

Neste artigo, você usou a CLI do Azure para simular um dispositivo e agendar trabalhos para executar um método direto e atualizar as propriedades do dispositivo gêmeo no dispositivo simulado.

Para continuar explorando os padrões de Hub IoT e de gerenciamento de dispositivo, atualize uma imagem no tutorial Atualização de dispositivo para o Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B +.

Compartilhar via