Agendar e transmitir trabalhos (CLI do Azure)

Artigo
07/17/2024

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

Atualizar as propriedades pretendidas
Atualizar tags
Invocar métodos diretos

Conceitualmente, um trabalho envolve uma dessas ações e rastreia o progresso da execução em relação a um conjunto de dispositivos. O conjunto de dispositivos com os quais um trabalho interage é definido por uma consulta gêmea de dispositivo. Por exemplo, um aplicativo back-end pode usar um trabalho para invocar um método de reinicialização em 10.000 dispositivos, especificado por uma consulta gêmea de dispositivo e agendado em um momento futuro. Esse aplicativo pode então 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:

Gêmeos e propriedades de dispositivos: Introdução aos gêmeos de dispositivo e Compreender e usar gêmeos de dispositivo no Hub IoT
Métodos diretos: Guia do desenvolvedor do Hub IoT - métodos diretos

Nota

Os recursos descritos neste artigo estão disponíveis somente na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha 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 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 gêmea de dispositivo desejada no dispositivo simulado criado na outra sessão.

Pré-requisitos

CLI do Azure. Você também pode executar os comandos neste artigo usando o Azure Cloud Shell, um shell interativo da CLI que é executado em seu navegador ou em um aplicativo como o Terminal do Windows. Se você usa o Cloud Shell, não precisa instalar nada. Se você preferir usar a CLI localmente, este artigo requer a CLI do Azure versão 2.36 ou posterior. Executar az --version para localizar a versão. Para instalar ou atualizar localmente a CLI do Azure, consulte Instalar a CLI do Azure.
Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo neste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

Preparar o Cloud Shell

Se quiser usar o Azure Cloud Shell, você deve primeiro iniciá-lo e configurá-lo. Se você usar a CLI localmente, vá para a seção Preparar duas sessões da CLI.

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

Nota

Se esta for a primeira vez que você usa o Cloud Shell, ele solicita que você crie armazenamento, que é necessário para usar o Cloud Shell. Selecione uma subscrição para criar uma conta de armazenamento e a partilha de Ficheiros 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 Bash . Você também pode usar o ambiente do PowerShell .

Nota

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 de CLI

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

A primeira sessão simula um dispositivo IoT que se comunica com seu hub IoT.
A segunda sessão agenda trabalhos para seu dispositivo simulado com seu hub IoT.

Nota

A CLI do Azure exige que você esteja conectado à sua conta do Azure. Se estiver a utilizar o Cloud Shell, inicia sessão automaticamente na sua conta do Azure. Se você estiver usando um cliente CLI local, deverá fazer login em cada sessão da CLI. Toda a comunicação entre sua sessão de shell da CLI do Azure e seu hub IoT é autenticada e criptografada. Como resultado, este artigo não precisa de 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, consulte 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 para CLI do Azure ao shell da CLI. A extensão adiciona comandos específicos do Hub IoT, IoT Edge e DPS (Serviço de Provisionamento de Dispositivos IoT) à CLI do Azure. Depois de instalar a extensão, não é necessário instalá-la novamente em nenhuma sessão do Cloud Shell.
```
az extension add --name azure-iot
```
Nota

Este artigo usa a versão mais recente da extensão do Azure IoT, chamada azure-iot. A versão herdada é chamada azure-cli-iot-extde . Você só deve ter uma versão instalada de cada vez. Você pode usar o comando az extension list para validar as extensões atualmente 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ê instalou, 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 sua 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 seu hub IoT na primeira sessão da CLI e, em seguida, simula um dispositivo usando essa identidade de 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 seguintes espaços reservados por seus valores correspondentes. Este comando cria a identidade do dispositivo para o dispositivo simulado.

{NomedoDispositivo}. O nome do seu dispositivo simulado.

{HubName}. O nome do 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 seguintes espaços reservados por seus valores correspondentes. Este comando simula o dispositivo que você criou na etapa anterior. O dispositivo simulado é configurado para retornar um código de status e carga útil sempre que um método direto é invocado.

{NomedoDispositivo}. O nome do seu dispositivo simulado.

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

Por padrão, o comando az iot device simulate envia 100 mensagens de dispositivo para nuvem com um intervalo de 3 segundos entre as mensagens. A simulação termina depois de todas as mensagens terem sido enviadas. Se quiser que a simulação seja executada por mais tempo, você pode usar o --msg-count parâmetro para especificar mais mensagens ou o --msg-interval parâmetro para especificar um intervalo maior 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 na primeira sessão da CLI 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 seguintes espaços reservados por seus valores correspondentes. Neste exemplo, não há nenhum método pré-existente 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 a carga útil do método. O método fornece um código de status e carga útil em sua resposta.

{HubName}. O nome do seu hub IoT.

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

{MethodName}. O nome do seu método direto. O dispositivo simulado não tem um método pré-existente, então você pode escolher qualquer nome que desejar para este comando.

{NomedoDispositivo}. O nome do seu 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}'"
```
Gorjeta

Ao agendar um comando job az iot hub job create que invoca um método direto, você deve especificar valores para os --method-name parâmetros opcionais e --method-payload opcionais. Para métodos diretos que não aceitam uma carga útil, especifique null o --method-payload parâmetro.
Na primeira sessão da CLI, confirme se a saída mostra a chamada do método. Na captura de tela a seguir, usamos SampleDevice eSampleMethod para os {DeviceName} espaços reservados e {MethodName} , respectivamente, no az iot hub job create comando CLI da etapa anterior.

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

Nesta seção, você agenda um trabalho na segunda sessão da CLI para atualizar uma propriedade gêmea do dispositivo desejado no dispositivo simulado em execução na primeira sessão da CLI.

Confirme se o dispositivo simulado na primeira sessão da CLI 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 seguintes espaços reservados por seus valores correspondentes. Neste exemplo, estamos agendando um trabalho para definir o valor da propriedade BuildingNo gêmea desejada como 45 para nosso dispositivo simulado.

{HubName}. O nome do seu hub IoT.

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

{NomedoDispositivo}. O nome do seu 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 gêmeo do dispositivo relatada, indicando que a propriedade gêmea do dispositivo desejada também foi atualizada.

Próximos passos

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 gêmeo de dispositivo para esse dispositivo simulado.

Para continuar explorando o hub IoT e os padrões de gerenciamento de dispositivos, 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+.

Partilhar via