Compartilhar via

Gerenciamento automático de módulos e dispositivos IoT usando a CLI do Azure

  • Artigo

O gerenciamento automático de dispositivo no Hub IoT do Azure automatiza muitas das tarefas repetitivas e complexas de gerenciamento de grande frotas de dispositivos. Com o gerenciamento automático de dispositivo, você pode direcionar um conjunto de dispositivos com base em suas propriedades, definir uma configuração desejada e permitir que o Hub IoT atualize dispositivos sempre que entrem 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, tratar a mesclagem e os conflitos e implementar configurações em uma abordagem em fases.

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.

O gerenciamento automático de dispositivo trabalha atualizando um conjunto de dispositivos gêmeos ou módulos gêmeos com as propriedades desejadas e informando um resumo com base em propriedades reportadas por gêmeos. Ele apresenta uma nova classe e um documento JSON denominado Configuração que tem três partes:

  • A condição de destino define o escopo de dispositivos gêmeos ou módulos gêmeos a serem atualizados. A condição de destino é especificada como uma consulta em marcas de dispositivos gêmeos e/ou propriedades reportadas.

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

  • As métricas definem as contagens de resumos de vários estados de configuração como êxito, em andamento, e erro. Métricas personalizadas são especificadas como consultas nas propriedades reportadas do gêmeo. As métricas do sistema são métricas padrão que medem o status de atualização do gêmeo, como o número de gêmeos definidos como destino 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 cada vez que a configuração automática é executada. Há suporte para no máximo 100 configurações automáticas em Hubs IoT da camada standard e no máximo dez em Hubs IoT da camada gratuita. Limitações também se aplicam. Saiba mais em Cotas e limitação.

Pré-requisitos da CLI

  • Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

  • CLI do Azure em seu ambiente. No mínimo, a versão da CLI do Azure deve ser 2.0.70 ou superior. Use az –-version para validar. Esta versão dá suporte aos comandos da extensão az e introduz a estrutura de comandos Knack.

  • A extensão de IoT para a CLI do Azure.

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.

Implementar gêmeos

As configurações automáticas de dispositivo requerem o uso de dispositivos gêmeos para sincronizar o estado entre a nuvem e os dispositivos. Para saber mais, veja Noções básicas e uso de dispositivos gêmeos no Hub IoT.

As configurações automáticas de módulo requerem o uso de módulos gêmeos para sincronizar o estado entre a nuvem e os módulos. Para obter mais informações, confira Noções básicas e uso de módulos gêmeos no Hub IoT.

Usar marcas para direcionar gêmeos

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

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

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

As consultas de métrica e conteúdo de destino são especificadas como documentos JSON que descrevem as propriedades desejadas de dispositivo gêmeo ou módulo gêmeo a serem definidas e as propriedades relatadas a serem medidas. 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. Você usará os caminhos de arquivo em uma próxima seção quando executar o comando para aplicar a configuração ao 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 de módulo se comportam de modo semelhante, mas você tem como destino moduleContent, em vez de deviceContent.

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

A seguir estão alguns 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 de dispositivos, mas você seleciona para moduleId de 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

É possível criar no máximo 100 configurações automáticas em Hubs IoT da camada standard e no máximo dez em Hubs IoT da camada gratuita. Saiba mais em Cotas e limitação.

Você configura dispositivos de destino criando uma configuração que consiste de métricas e conteúdo de destino. Use o comando a seguir 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ê um nome exclusivo à sua configuração de até 128 caracteres de comprimento. Letras minúsculas e os seguintes caracteres especiais são permitidos: -+%_*!'. Espaços não são permitidos.

  • --labels - Adicione rótulos para ajudar a rastrear a configuração. Rótulos são pares de Nome e Valor que descrevem a implantação. Por exemplo, HostPlatform, Linux ou Version, 3.0.1

  • --content - JSON em linha ou caminho de arquivo para o conteúdo de destino a ser configurado como propriedades desejadas do gêmeo.

  • --hub-name - Nome do Hub IoT no qual a configuração será criada. O hub deve estar na assinatura atual. Alterne para a assinatura desejada 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 segmentados com essa configuração. Para configuração automática de dispositivo, a condição é baseada nas marcações do dispositivo gêmeo ou nas propriedades desejadas do dispositivo gêmeo e deve corresponder ao formato da expressão. Por exemplo, tags.environment='test' ou properties.desired.devicemodel='4000x'. Para a configuração automática de módulo, a condição é baseada nas marcas do módulo gêmeo ou nas propriedades desejadas do 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 inteiro positivo. No caso de duas ou mais configurações a serem direcionadas ao mesmo dispositivo ou módulo, será aplicada a configuração com o maior valor numérico para Prioridade.

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

Monitorar uma configuração

Use o comando a seguir 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. Alterne para a assinatura desejada 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 dispositivos gêmeos ou módulos gêmeos no Hub IoT que correspondem à condição de direcionamento.

  • appliedCount – uma métrica de 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.

É possível mostrar uma lista de IDs de dispositivos, 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 dispositivos ou IDs de módulos, por exemplo, appliedCount.

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

  • --metric-type - O tipo de métrica pode ser system ou user. Métricas de 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 direcionados.

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

  • Caso um gêmeo não tenha atendido à condição de destino antiga, mas atenda à nova condição de destino e essa configuração tenha a prioridade mais alta para o gêmeo, essa configuração será aplicada.

  • Se um gêmeo que executa essa configuração no momento não atender mais à condição de destino, as definiçõ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 que executa essa configuração no momento não atende à condição de destino e não atende a condição destino de outras configurações, as definições da configuração serão removidas e nenhuma outra alteração será feita no gêmeo.

Use o comando a seguir 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. Alterne para a assinatura desejada 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

    • priority

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 atendem a condição destino de qualquer outra configuração, não serão aplicadas outras configurações.

Use o comando a seguir 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. Alterne para a assinatura desejada com o comando az account set -s [subscription name].

Próximas etapas

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

Para aprender a gerenciar identidades de dispositivo do Hub IoT em massa, confira Importar e exportar identidades de dispositivo do Hub IoT em massa