Gestão automática de módulos e dispositivos IoT com a CLI do Azure

Artigo
03/17/2023

A gestão automática de dispositivos no Hub IoT do Azure automatiza muitas das tarefas repetitivas e complexas de gestão de frotas de dispositivos grandes. Com a gestão automática de dispositivos, pode direcionar um conjunto de dispositivos com base nas respetivas propriedades, definir uma configuração pretendida e, em seguida, permitir que Hub IoT atualizem os dispositivos quando entrarem no âmbito. Esta atualização é efetuada com uma configuração automática do dispositivo ou uma configuração automática do módulo, que lhe permite resumir a conclusão e conformidade, processar intercalação e conflitos e implementar configurações numa abordagem faseada.

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.

A gestão automática de dispositivos funciona ao atualizar um conjunto de dispositivos duplos ou módulos duplos com as propriedades pretendidas e ao comunicar um resumo baseado em propriedades reportadas de duplos. Apresenta uma nova classe e um documento JSON denominado configuração que tem três partes:

A condição de destino define o âmbito dos dispositivos duplos ou módulos duplos a atualizar. A condição de destino é especificada como uma consulta em etiquetas de dispositivo duplo e/ou propriedades reportadas.
O conteúdo de destino define as propriedades pretendidas a serem adicionadas ou atualizadas nos dispositivos duplos ou módulos duplos de destino. O conteúdo inclui um caminho para a secção das propriedades pretendidas a alterar.
As métricas definem as contagens de resumo de vários estados de configuração, como Êxito, Em Curso e Erro. As métricas personalizadas são especificadas como consultas em propriedades reportadas de duplos. As métricas do sistema são as métricas predefinidas que medem o estado da atualização de duplos, como o número de duplos visados e o número de duplos que foram atualizados com êxito.

As configurações automáticas são executadas pela primeira vez pouco depois de a configuração ser criada e, em seguida, em intervalos de cinco minutos. As consultas de métricas são executadas sempre que a configuração automática é executada. É suportado um máximo de 100 configurações automáticas nos hubs IoT de escalão standard; dez em hubs IoT de escalão gratuito. Também se aplicam limites de limitação. Para saber mais, veja Quotas e Limitação.

Pré-requisitos da CLI

Um hub IoT na sua subscrição do Azure.
CLI do Azure no seu ambiente. No mínimo, a versão da CLI do Azure tem de ser 2.0.70 ou superior. Utilize az –-version para validar. Esta versão suporta comandos de extensão az e apresenta a arquitetura de comandos Knack.
A extensão IoT para a CLI do Azure.

Nota

Este artigo utiliza a versão mais recente da extensão do Azure IoT, denominada azure-iot. A versão legada chama-se 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.

Implementar duplos

As configurações automáticas de dispositivos requerem a utilização de dispositivos duplos para sincronizar o estado entre a cloud e os dispositivos. Para obter mais informações, veja Compreender e utilizar dispositivos duplos no Hub IoT.

As configurações automáticas dos módulos requerem a utilização de módulos duplos para sincronizar o estado entre a cloud e os módulos. Para obter mais informações, veja Compreender e utilizar módulos duplos no Hub IoT.

Utilizar etiquetas para direcionar duplos

Antes de criar uma configuração, tem de especificar os dispositivos ou módulos que pretende afetar. Hub IoT do Azure identifica dispositivos e utiliza etiquetas no dispositivo duplo e identifica módulos com etiquetas no módulo duplo. Cada dispositivo ou módulo pode ter várias etiquetas e pode defini-las de qualquer forma que faça sentido para a sua solução. Por exemplo, se gerir dispositivos em localizações diferentes, adicione as seguintes etiquetas a um dispositivo duplo:

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

Definir o conteúdo e as métricas de destino

As consultas de métricas e conteúdo de destino são especificadas como documentos JSON que descrevem as propriedades pretendidas do dispositivo duplo ou do módulo duplo a definir e as propriedades comunicadas a medir. Para criar uma configuração automática com a CLI do Azure, guarde o conteúdo de destino e as métricas localmente como .txt ficheiros. Utilize os caminhos de ficheiro numa secção posterior quando executar o comando para aplicar a configuração ao seu dispositivo.

Eis um exemplo de conteúdo de destino básico para uma configuração automática do dispositivo:

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

As configurações automáticas dos módulos comportam-se de forma muito semelhante, mas são direcionadas moduleContent em vez de deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Eis exemplos de consultas de métricas:

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

As consultas de métricas para módulos também são semelhantes às consultas dos dispositivos, mas seleciona para moduleId em devices.modules. Por exemplo:

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

Criar uma configuração

Pode criar um máximo de 100 configurações automáticas em hubs IoT de escalão standard; dez em hubs IoT de escalão gratuito. Para saber mais, veja Quotas e Limitação.

Pode configurar dispositivos de destino ao criar uma configuração que consiste no conteúdo de destino e nas métricas. Utilize o seguinte comando para criar uma configuração:

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

--config-id - O nome da configuração que será criada no hub IoT. Atribua um nome exclusivo à configuração com até 128 carateres. São permitidas letras minúsculas e os seguintes carateres especiais: -+%_*!'. Não são permitidos espaços.
--etiquetas – adicione etiquetas para ajudar a controlar a configuração. As etiquetas são Os pares Nome e Valor que descrevem a sua implementação. Por exemplo, HostPlatform, Linux ou Version, 3.0.1
--content - JSON inline ou caminho de ficheiro para o conteúdo de destino a definir como propriedades pretendidas de duplos.
--hub-name - Nome do hub IoT no qual a configuração será criada. O hub tem de estar na subscrição atual. Mudar para a subscrição pretendida com o comando az account set -s [subscription name]
--target-condition - Introduza uma condição de destino para determinar que dispositivos ou módulos serão visados com esta configuração. Para a configuração automática do dispositivo, a condição baseia-se em etiquetas de dispositivo duplo ou propriedades pretendidas do dispositivo duplo e deve corresponder ao formato de expressão. Por exemplo, tags.environment='test' ou properties.desired.devicemodel='4000x'. Para a configuração automática do módulo, a condição baseia-se em etiquetas de módulo duplo ou propriedades pretendidas do módulo duplo. Por exemplo, from devices.modules where tags.environment='test' ou from devices.modules where properties.reported.chillerProperties.model='4000x'.
--priority - Um número inteiro positivo. No caso de duas ou mais configurações serem direcionadas para o mesmo dispositivo ou módulo, será aplicada a configuração com o valor numérico mais elevado para Prioridade.
--metrics - Filepath para as consultas de métricas. As métricas fornecem contagens de resumo dos vários estados que um dispositivo ou módulo pode comunicar após a aplicação do conteúdo de configuração. Por exemplo, pode criar uma métrica para alterações de definições pendentes, uma métrica para erros e uma métrica para alterações de definições bem-sucedidas.

Monitorizar uma configuração

Utilize o seguinte comando para apresentar o conteúdo de uma configuração:

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

--config-id - O nome da configuração que existe no hub IoT.
--hub-name - Nome do hub IoT no qual a configuração existe. O hub tem de estar na subscrição atual. Mudar para a subscrição pretendida com o comando az account set -s [subscription name]

Inspecione a configuração na janela de comandos. A propriedade metrics lista uma contagem para cada métrica que é avaliada por cada hub:

targetedCount - uma métrica de sistema que especifica o número de dispositivos duplos ou módulos duplos no Hub IoT que correspondem à condição de destino.
appliedCount - Uma métrica de sistema especifica o número de dispositivos ou módulos que tiveram o conteúdo de destino aplicado.
A sua métrica personalizada – todas as métricas que definiu são métricas de utilizador.

Pode mostrar uma lista de IDs de dispositivo, IDs de módulo ou objetos para cada uma das métricas com o seguinte comando:

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

--config-id - O nome da implementação que existe no hub IoT.
--metric-id - O nome da métrica para a qual pretende ver a lista de IDs de dispositivo ou IDs do módulo, por exemplo appliedCount.
--hub-name - Nome do hub IoT no qual a implementação existe. O hub tem de estar na subscrição atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].
--metric-type - O tipo de métrica pode ser system ou user. As métricas do sistema são targetedCount e appliedCount. Todas as outras métricas são métricas de utilizador.

Modificar uma configuração

Quando modifica uma configuração, as alterações são imediatamente replicadas para todos os dispositivos visados.

Se atualizar a condição de destino, ocorrem as seguintes atualizações:

Se um duplo não cumprir a condição de destino antiga, mas cumprir a nova condição de destino e esta configuração for a prioridade mais alta para esse duplo, esta configuração é aplicada.
Se um duplo atualmente a executar esta configuração já não cumprir a condição de destino, as definições da configuração serão removidas e o duplo será modificado pela próxima configuração de prioridade mais alta.
Se um duplo atualmente a executar esta configuração já não cumprir a condição de destino e não cumprir a condição de destino de quaisquer outras configurações, as definições da configuração serão removidas e não serão efetuadas outras alterações no duplo.

Utilize o seguinte comando para atualizar uma configuração:

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

--config-id – o nome da configuração que existe no hub IoT.
--hub-name - Nome do hub IoT no qual a configuração existe. O hub tem de estar na subscrição atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].
--set - Atualize uma propriedade na configuração. Pode atualizar as seguintes propriedades:
- targetCondition - por exemplo targetCondition=tags.location.state='Oregon'
- etiquetas
- prioridade

Eliminar uma configuração

Quando elimina uma configuração, todos os dispositivos duplos ou módulos duplos assumem a configuração de prioridade mais próxima. Se os duplos não cumprirem a condição de destino de qualquer outra configuração, não serão aplicadas outras definições.

Utilize o seguinte comando para eliminar uma configuração:

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

--config-id – o nome da configuração que existe no hub IoT.
--hub-name - Nome do hub IoT no qual a configuração existe. O hub tem de estar na subscrição atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].

Passos seguintes

Neste artigo, aprendeu a configurar e monitorizar dispositivos IoT em escala.

Para saber como gerir Hub IoT identidades de dispositivos em massa, veja Importar e exportar identidades de dispositivos Hub IoT em massa

Share via