Agendar e transmitir tarefas (CLI do Azure)

Artigo
03/18/2023

Utilize Hub IoT do Azure para agendar e controlar tarefas que atualizam milhões de dispositivos. Utilizar tarefas para:

Atualizar as propriedades pretendidas
Atualizar etiquetas
Invocar métodos diretos

Conceptualmente, uma tarefa encapsula uma destas ações e controla o progresso da execução num conjunto de dispositivos. O conjunto de dispositivos com os quais uma tarefa interage é definido por uma consulta de dispositivo duplo. Por exemplo, uma aplicação de back-end pode utilizar uma tarefa para invocar um método de reinício em 10 000 dispositivos, especificado por uma consulta de dispositivo duplo e agendado numa hora futura. Essa aplicação pode, em seguida, controlar o progresso à medida que cada um desses dispositivos recebe e executa o método de reinício.

Saiba mais sobre cada uma destas capacidades nestes artigos:

Dispositivo duplo e propriedades: introdução aos dispositivos duplos e Compreender e utilizar dispositivos duplos no Hub IoT
Métodos diretos: Hub IoT guia para programadores – métodos diretos

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão do Hub IoT. Para obter mais informações sobre os escalões de Hub IoT básico e standard/gratuito, consulte Escolher o escalão de Hub IoT certo para a sua solução.

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

Uma sessão que cria um dispositivo simulado. O dispositivo simulado está configurado para devolver um código de estado e um payload JSON quando qualquer método direto é invocado.
Uma sessão que cria duas tarefas agendadas. A primeira tarefa invoca um método direto e a segunda tarefa atualiza uma propriedade de dispositivo duplo pretendido no dispositivo simulado criado na outra sessão.

Pré-requisitos

CLI do Azure. Também pode executar os comandos neste artigo com o Azure Cloud Shell, uma shell interativa da CLI que é executada no seu browser ou numa aplicação, como Terminal do Windows. Se utilizar a Cloud Shell, não precisa de instalar nada. Se preferir utilizar a CLI localmente, este artigo requer a versão 2.36 ou posterior da CLI do Azure. Executar az --version para localizar a versão. Para instalar ou atualizar localmente a CLI do Azure, veja Instalar a CLI do Azure.
Um hub IoT na sua subscrição do Azure. Crie uma com a CLI ou a portal do Azure.
Certifique-se de que a porta 8883 está aberta na firewall. O exemplo de dispositivo neste artigo utiliza o protocolo MQTT, que comunica através da porta 8883. Esta porta pode ser bloqueada em alguns ambientes de rede empresarial e educacional. Para obter mais informações e formas de contornar este problema, veja Ligar ao Hub IoT (MQTT).

Preparar a Cloud Shell

Se quiser utilizar a Cloud Shell do Azure, primeiro tem de a iniciar e configurar. Se utilizar a CLI localmente, avance para a secção Preparar duas sessões da CLI .

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

Nota

Se esta for a primeira vez que utiliza o Cloud Shell, pede-lhe para criar armazenamento, que é necessário para utilizar o Cloud Shell. Selecione uma subscrição para criar uma conta de armazenamento e a partilha de Ficheiros do Microsoft Azure.
Utilize o seletor de ambiente na barra de ferramentas Cloud Shell para selecionar o ambiente da CLI preferencial. Este artigo utiliza o ambiente bash . Também pode utilizar o ambiente do PowerShell .

Nota

Alguns comandos requerem sintaxe ou formatação diferentes nos ambientes do Bash e do PowerShell . Para obter mais informações, veja Sugestões para utilizar a CLI do Azure com êxito.

Preparar duas sessões da CLI

Em seguida, tem de preparar duas sessões da CLI do Azure. Se estiver a utilizar o Cloud Shell, execute estas sessões em separadores Cloud Shell separadores separadores. Se utilizar um cliente da CLI local, execute instâncias da CLI separadas. Utilize as sessões separadas da CLI para as seguintes tarefas:

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

Nota

A CLI do Azure requer que tenha sessão iniciada na sua conta do Azure. Se estiver a utilizar o Cloud Shell, tem sessão iniciada automaticamente na sua conta do Azure. Se estiver a utilizar um cliente da CLI local, tem de iniciar sessão em cada sessão da CLI. Toda a comunicação entre a sessão da shell da CLI do Azure e o hub IoT é autenticada e encriptada. Como resultado, este artigo não precisa de autenticação extra que utilizaria com um dispositivo real, como uma cadeia de ligação. Para obter mais informações sobre como iniciar sessão com a CLI do Azure, veja Iniciar sessão 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 a CLI do Azure à shell da CLI. A extensão adiciona comandos específicos Hub IoT, IoT Edge e IoT Device Provisioning Service (DPS) à CLI do Azure. Depois de instalar a extensão, não precisa de instalá-la novamente em nenhuma Cloud Shell sessão.
```
az extension add --name azure-iot
```
Nota

Este artigo utiliza a versão mais recente da extensão do Azure IoT, denominada azure-iot. A versão legada é denominada azure-cli-iot-ext. Só deve ter uma versão instalada de cada vez. Pode utilizar o comando az extension list para validar as extensões atualmente instaladas.

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

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

Para ver que extensões instalou, utilize az extension list.
Abra a segunda sessão da CLI. Se estiver a utilizar o Cloud Shell num browser, selecione o ícone Abrir nova sessão na barra de ferramentas da sua primeira sessão da CLI. Se estiver a utilizar a CLI localmente, abra uma segunda instância da CLI.

Criar e simular um dispositivo

Nesta secção, vai criar uma identidade de dispositivo para o seu hub IoT na primeira sessão da CLI e, em seguida, simular um dispositivo com essa identidade de dispositivo. O dispositivo simulado responde às tarefas agendadas 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 marcadores de posição pelos valores correspondentes. Este comando cria a identidade do dispositivo para o seu dispositivo simulado.

{DeviceName}. 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 marcadores de posição pelos valores correspondentes. Este comando simula o dispositivo que criou no passo anterior. O dispositivo simulado está configurado para devolver um código de estado e um payload sempre que um método direto é invocado.

{DeviceName}. 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"}'
```
Dica

Por predefinição, o comando az iot device simulate envia 100 mensagens do dispositivo para a cloud 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 mais tempo, pode utilizar o --msg-count parâmetro para especificar mais mensagens ou o --msg-interval parâmetro para especificar um intervalo mais longo entre as mensagens. Também pode executar o comando novamente para reiniciar o dispositivo simulado.

Agendar uma tarefa para invocar um método direto

Nesta secção, vai agendar uma tarefa 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 que o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o ao executar novamente o comando az iot device simulate a partir de Criar e simular um dispositivo.
Na segunda sessão da CLI, execute o comando az iot hub job create , substituindo os seguintes marcadores de posição pelos valores correspondentes. Neste exemplo, não existe nenhum método pré-existente para o dispositivo. O comando agenda uma tarefa que chama um nome de método de exemplo no dispositivo simulado, fornecendo um valor nulo para o payload do método. O método fornece um código de estado e um payload na resposta.

{HubName}. O nome do seu hub IoT.

{JobName}. O nome da sua tarefa agendada. Os nomes dos trabalhos são exclusivos, por isso escolha um nome de tarefa diferente sempre que executar este comando.

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

{DeviceName}. 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}'"
```
Dica

Ao agendar um trabalho az iot hub job create comando que invoca um método direto, tem de especificar valores para os --method-name parâmetros e --method-payload opcionais. Para métodos diretos que não aceitam um payload, especifique null para o --method-payload parâmetro .
Na primeira sessão da CLI, confirme que o resultado mostra a invocação do método. Na captura de ecrã seguinte, utilizámos SampleDevice e para os {DeviceName} marcadores de posição e{MethodName}, respetivamente, no comando da az iot hub job create CLISampleMethod do passo anterior.

Agendar uma tarefa para atualizar as propriedades de um dispositivo duplo

Nesta secção, vai agendar uma tarefa na segunda sessão da CLI para atualizar uma propriedade de dispositivo duplo pretendido no dispositivo simulado em execução na primeira sessão da CLI.

Confirme que o dispositivo simulado na primeira sessão da CLI está em execução. Caso contrário, reinicie-o ao executar novamente o comando az iot device simulate a partir de Criar e simular um dispositivo.
Na segunda sessão da CLI, execute o comando az iot hub job create , substituindo os seguintes marcadores de posição pelos valores correspondentes. Neste exemplo, estamos a agendar uma tarefa para definir o valor da propriedade BuildingNo do duplo pretendido como 45 para o nosso dispositivo simulado.

{HubName}. O nome do seu hub IoT.

{JobName}. O nome da sua tarefa agendada. Os nomes dos trabalhos são exclusivos, por isso escolha um nome de tarefa diferente sempre que executar este comando.

{DeviceName}. 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 que o resultado mostra a atualização com êxito da propriedade do dispositivo duplo reportado, indicando que a propriedade do dispositivo duplo pretendido também foi atualizada.

Passos seguintes

Neste artigo, utilizou a CLI do Azure para simular um dispositivo e agendar tarefas para executar um método direto e atualizar as propriedades do dispositivo duplo para esse dispositivo simulado.

Para continuar a explorar padrões de gestão de dispositivos e hub IoT, atualize uma imagem no tutorial Atualização de Dispositivos para Hub IoT do Azure com a Imagem de Referência raspberry Pi 3 B+.

Share via