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

O gerenciamento automático de dispositivos no Hub IoT do Azure automatiza muitas das tarefas repetitivas e complexas do gerenciamento de grandes frotas de dispositivos. Com o gerenciamento automático de dispositivos, você pode direcionar um conjunto de dispositivos com base em suas propriedades, definir uma configuração desejada e, em seguida, permitir que o Hub IoT atualize os dispositivos quando eles entrarem no escopo. Essa atualização é feita usando uma configuração automática de dispositivo ou configuração automática de módulo, que permite resumir a conclusão e a conformidade, lidar com mesclagens e conflitos e implantar configurações em uma abordagem em fases.

O gerenciamento automático de dispositivos funciona atualizando um conjunto de gêmeos de dispositivo ou gêmeos de módulo com propriedades desejadas e relatando um resumo baseado em propriedades relatadas por gêmeos. Ele introduz uma nova classe e documento JSON chamado uma configuração que tem três partes:

• A condição de destino define o escopo dos gêmeos de dispositivo ou gêmeos de módulo a serem atualizados. A condição de destino é especificada como uma consulta em tags gêmeas de dispositivo e/ou propriedades relatadas.

• O conteúdo de destino define as propriedades desejadas a serem adicionadas ou atualizadas nos gêmeos de dispositivo ou de módulo de destino. O conteúdo inclui um caminho para a seção de propriedades desejadas a serem alteradas.

• As métricas definem as contagens de resumo de vários estados de configuração, como Sucesso, Em Andamento e Erro. As métricas personalizadas são especificadas como consultas em propriedades geminadas relatadas. As métricas do sistema são as métricas padrão que medem o status de atualização de gêmeos, como o número de gêmeos que são direcionados e o número de gêmeos que foram atualizados com êxito.

As configurações automáticas são executadas pela primeira vez logo após 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. Um máximo de 100 configurações automáticas é suportado em hubs IoT de camada padrão; dez em hubs IoT de nível gratuito. Os limites de limitação também se aplicam. Para saber mais, consulte Cotas e limitação.

Pré-requisitos da CLI

• Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.

• CLI do Azure em seu ambiente. No mínimo, sua versão da CLI do Azure deve 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 CLI do Azure.

Implementar gêmeos

As configurações automáticas de dispositivos exigem o uso de gêmeos de dispositivos para sincronizar o estado entre a nuvem e os dispositivos. Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

As configurações automáticas de módulos exigem o uso de gêmeos de módulo para sincronizar o estado entre a nuvem e os módulos. Para obter mais informações, consulte Compreender e usar gêmeos de módulo no Hub IoT.

Use tags para segmentar gêmeos

Antes de criar uma configuração, você deve especificar quais dispositivos ou módulos deseja afetar. O Hub IoT do Azure identifica dispositivos e marcas no gêmeo de dispositivo e identifica módulos usando marcas no gêmeo de módulo. Cada dispositivo ou módulo pode ter várias tags e você pode defini-las de qualquer maneira que faça sentido para sua solução. Por exemplo, se você gerenciar dispositivos em locais diferentes, adicione as seguintes tags a um gêmeo de dispositivo:

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

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

As consultas de conteúdo e métrica de destino são especificadas como documentos JSON que descrevem as propriedades desejadas do gêmeo de dispositivo ou do gêmeo de módulo a serem definidas e as propriedades relatadas para medir. Para criar uma configuração automática usando a CLI do Azure, salve o conteúdo e as métricas de destino localmente como arquivos .txt. Use os caminhos de arquivo em uma seção posterior quando executar o comando para aplicar a configuração ao seu dispositivo.

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

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

As configurações automáticas do módulo se comportam de forma muito semelhante, mas você segmenta moduleContent em vez de deviceContent.

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

Aqui estão exemplos de consultas 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 métricas para módulos também são semelhantes às consultas para dispositivos, mas você seleciona para moduleId 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

Você pode criar um máximo de 100 configurações automáticas em hubs IoT de camada padrão; dez em hubs IoT de nível gratuito. Para saber mais, consulte Cotas e limitação.

Configure os dispositivos de destino criando uma configuração que consiste no conteúdo e nas métricas de destino. Use 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. Dê à sua configuração um nome exclusivo com até 128 caracteres. São permitidas letras minúsculas e os seguintes caracteres especiais: -+%_*!'. Não são permitidos espaços.

• --etiquetas - Adicione etiquetas para ajudar a controlar a sua configuração. Os rótulos são pares Nome, Valor que descrevem sua implantação. Por exemplo, HostPlatform, Linux ou Version, 3.0.1

• --content - JSON embutido ou caminho de arquivo para o conteúdo de destino a ser definido como propriedades desejadas gêmeas.

• --hub-name - Nome do hub IoT no qual a configuração será criada. O hub deve estar na assinatura atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name]

• --target-condition - Insira uma condição de destino para determinar quais dispositivos ou módulos serão direcionados com essa configuração. Para a configuração automática do dispositivo, a condição é baseada em tags gêmeas de dispositivo ou propriedades desejadas de gêmeo de dispositivo 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 é baseada em tags de módulo duplo ou propriedades desejadas de módulo gêmeo. 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, a configuração com o maior valor numérico para Prioridade será aplicada.

• --metrics - Filepath para as consultas de métrica. As métricas fornecem contagens resumidas dos vários estados que um dispositivo ou módulo pode relatar após a aplicação do conteúdo de configuração. Por exemplo, você pode criar uma métrica para alterações de configurações pendentes, uma métrica para erros e uma métrica para alterações de configurações bem-sucedidas.

Monitorar uma configuração

Use o seguinte comando para exibir 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 deve estar na assinatura atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name]

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

• targetedCount - Uma métrica do sistema que especifica o número de gêmeos de dispositivo ou gêmeos de módulo no Hub IoT que correspondem à condição de segmentação.

• appliedCount - Uma métrica do sistema especifica o número de dispositivos ou módulos que tiveram o conteúdo de destino aplicado.

• Sua métrica personalizada - Todas as métricas que você definiu são métricas de usuário.

Você pode mostrar uma lista de IDs de dispositivo, IDs de módulo ou objetos para cada uma das métricas usando 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 implantação que existe no hub IoT.

• --metric-id - O nome da métrica para a qual você deseja ver a lista de IDs de dispositivo ou IDs de módulo, por exemplo appliedCount.

• --hub-name - Nome do hub IoT no qual a implantação existe. O hub deve estar na assinatura atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].

• --tipo métrico - 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 do usuário.

Modificar uma configuração

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

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

• Se um gêmeo não atendesse à condição de destino antigo, mas atendesse à nova condição de destino e essa configuração fosse a prioridade mais alta para esse gêmeo, essa configuração seria aplicada.

• Se um gêmeo atualmente executando essa configuração não atender mais à condição de destino, as configurações da configuração serão removidas e o gêmeo será modificado pela próxima configuração de prioridade mais alta.

• Se um gêmeo atualmente executando essa configuração não atender mais à condição de destino e não atender à condição de destino de nenhuma outra configuração, as configurações da configuração serão removidas e nenhuma outra alteração será feita no gêmeo.

Use 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 deve estar na assinatura atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].

• --set - Atualize uma propriedade na configuração. Você pode atualizar as seguintes propriedades:

  • targetCondition - por exemplo targetCondition=tags.location.state='Oregon'

  • rótulos

  • prioridade

Excluir uma configuração

Quando você exclui uma configuração, qualquer dispositivo gêmeo ou módulo gêmeo assume sua próxima configuração de prioridade mais alta. Se os gêmeos não atenderem à condição de destino de qualquer outra configuração, nenhuma outra configuração será aplicada.

Use o seguinte comando para excluir 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 deve estar na assinatura atual. Mude para a subscrição pretendida com o comando az account set -s [subscription name].

Próximos passos

Neste artigo, você aprendeu como configurar e monitorar dispositivos IoT em escala.

Para saber como gerenciar identidades de dispositivo do Hub IoT em massa, consulte Importar e exportar identidades de dispositivo do Hub IoT em massa