Gestão automática de dispositivos e módulos IoT

Pré-requisitos

• Uma assinatura ativa do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• Um hub IoT em sua assinatura do Azure. Se ainda não tem um hub, pode seguir os passos na secção Criar um hub IoT de Criar e gerir hubs IoT 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 Azure IoT Hub identifica dispositivos usando tags no gêmeo digital do dispositivo e identifica módulos usando tags no gêmeo digital do 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"
    }
},

Criar uma configuração

Pode criar um máximo de 100 configurações automáticas em hubs IoT de nível padrão; 10 em hubs IoT de nível gratuito. Para saber mais, consulte quotas e limitações do IoT Hub.

1. No portal do Azure, vá para o seu hub IoT.

2. No menu de serviço, em Gestão de Dispositivos, selecione Configurações + Implementações.

3. Selecione Adicionar e escolha Configuração gémea de dispositivo ou configuração gémea de módulo na lista suspensa.

   

Há cinco etapas para criar uma configuração. As seções a seguir percorrem cada uma delas.

Nome e rótulo

1. Introduza um nome único para a sua configuração. O nome pode ter até 128 caracteres e pode incluir letras minúsculas e os seguintes caracteres especiais: -+%_*!'. Não são permitidos espaços.
2. Adiciona etiquetas para organizar e descrever a tua configuração. Os rótulos são pares-chave-valor, como HostPlatform, Linux ou Version, 3.0.1.
3. Selecione Seguinte para continuar.

Configurações gêmeas

Defina o conteúdo nas propriedades gemelas de dispositivo ou módulo desejadas fornecendo duas entradas para cada definição. Primeiro, especifique o caminho gémeo, que aponta para a secção JSON dentro das propriedades gémeas desejadas a atualizar. De seguida, introduza o conteúdo JSON para inserir nesse local.

Por exemplo, você pode definir o caminho gêmeo para properties.desired.chiller-water e, em seguida, fornecer o seguinte conteúdo JSON:

{
  "temperature": 66,
  "pressure": 28
}

Você também pode definir configurações individuais especificando o caminho gêmeo inteiro e fornecendo o valor sem colchetes. Por exemplo, com o caminho gêmeo properties.desired.chiller-water.temperature, defina o conteúdo como 66. Em seguida, crie uma nova configuração dupla para a propriedade de pressão.

Se duas ou mais configurações tiverem como alvo o mesmo caminho gémeo, aplica-se o conteúdo da configuração de maior prioridade (a prioridade é definida no passo 4).

Se desejar remover uma propriedade existente, especifique o valor da propriedade para null.

Pode adicionar mais definições selecionando Adicionar Configuração Gémea de Dispositivo ou Adicionar Configuração Gémea de Módulo.

Dispositivos ou módulos alvo

Use a propriedade tags dos vossos gêmeos para direcionar os dispositivos ou módulos específicos que devem receber esta configuração. Você também pode focar em propriedades gêmeas relatadas.

As configurações automáticas de dispositivos podem apenas direcionar etiquetas gêmeas de dispositivos e as configurações automáticas de módulos podem apenas direcionar etiquetas gêmeas de módulos.

Como múltiplas configurações podem ter como alvo o mesmo dispositivo ou módulo, cada configuração necessita de um número de prioridade. Se houver algum conflito, vence a configuração com a prioridade mais alta.

1. Insira um número inteiro positivo para a configuração Prioridade. O valor numérico mais alto é considerado a prioridade mais alta. Se duas configurações tiverem o mesmo número de prioridade, a criada mais recentemente vence.

2. Introduza uma condição de Alvo para determinar que dispositivos ou módulos são visados com esta configuração. A condição é baseada em tags gêmeas ou propriedades relatadas de gêmeos e deve corresponder ao formato da expressão.

   • Para a configuração automática do dispositivo, pode-se especificar apenas a tag ou a propriedade reportada a ser direcionada. Por exemplo, tags.environment='test' ou properties.reported.chillerProperties.model='4000x'. Você pode especificar * para atingir todos os dispositivos.

   • Para configuração automática de módulos, use uma consulta para especificar tags ou propriedades relatadas dos módulos registrados no hub IoT. Por exemplo, from devices.modules where tags.environment='test' ou from devices.modules where properties.reported.chillerProperties.model='4000x'. O wildcard não pode ser usado para direcionar todos os módulos.

Métricas

As métricas fornecem contagens resumidas dos vários estados que um dispositivo ou módulo pode reportar após aplicar o conteúdo de configuração. Por exemplo, pode criar uma métrica para alterações pendentes nas definições, uma métrica para erros e uma métrica para alterações bem-sucedidas nas definições.

Cada configuração pode ter até cinco métricas personalizadas.

1. Insira um nome para Metric Name.

2. Insira uma consulta para os Critérios de Métricas . A consulta é baseada nas propriedades relatadas do gêmeo digital do dispositivo. A métrica representa o número de linhas retornadas pela consulta.

   Por exemplo:

   SELECT deviceId FROM devices 
     WHERE properties.reported.chillerWaterSettings.status='pending'
   

   Você pode incluir uma cláusula de que a configuração foi aplicada, por exemplo:

   /* Include the double brackets. */
   SELECT deviceId FROM devices 
     WHERE configurations.[[yourconfigname]].status='Applied'
   

   Se você estiver criando uma métrica para gerar relatórios sobre módulos configurados, selecione moduleId em devices.modules. Por exemplo:

   SELECT deviceId, moduleId FROM devices.modules
     WHERE properties.reported.lastDesiredStatus.code = 200
   

Rever a configuração

Reveja os seus dados de configuração e selecione Enviar.

Monitorar uma configuração

Para exibir os detalhes de uma configuração e monitorar os dispositivos que a executam, use as seguintes etapas:

1. No portal do Azure, vá para o seu hub IoT.

2. No menu de serviço, em Gestão de Dispositivos, selecione Configurações + Implementações.

3. Inspecione a lista de configurações. Para cada configuração, você pode exibir os seguintes detalhes:

   • ID - o nome da configuração.

   • Condição de destino - a consulta usada para definir dispositivos ou módulos de destino.

   • Prioridade - o número de prioridade atribuído à configuração.

   • Hora de criação - o registo temporal em que a configuração foi criada. Este timestamp é usado para desempatar quando duas configurações têm a mesma prioridade.

   • Métricas do sistema - métricas que são calculadas pelo IoT Hub e que não podem ser personalizadas pelos programadores. Target especifica o número de dispositivos gémeos que correspondem à condição alvo. Aplica especifica o número de gémeos de dispositivo que são modificados pela configuração, o que pode incluir modificações parciais caso uma configuração separada e de prioridade superior também tenha feito alterações.

   • Métricas personalizadas - métricas especificadas pelo desenvolvedor como consultas às propriedades reportadas por twin. Até cinco métricas personalizadas podem ser definidas por configuração.

4. Selecione a configuração que você deseja monitorar.

5. Inspecione os detalhes da configuração. Você pode usar guias para exibir detalhes específicos sobre os dispositivos que receberam a configuração.

   • Dispositivos Alvo ou Módulos Alvo - os dispositivos ou módulos que atendem à condição alvo.

   • Metrics - uma lista de métricas do sistema e métricas personalizadas. Você pode ver uma lista de dispositivos ou módulos que são contabilizados para cada métrica ao selecionar a métrica no menu suspenso e, em seguida, escolher Ver Dispositivos ou Ver Módulos.

   • Labels - pares chave-valor usados para descrever a configuração. Os rótulos não têm impacto na funcionalidade.

   • Configurações gêmeas do dispositivo ou Configurações gêmeas do módulo - as configurações gêmeas definidas pela configuração, se houver.

Modificar uma configuração

Quando você modifica uma configuração, as alterações são replicadas imediatamente para todos os dispositivos ou módulos 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 twin que atualmente executa esta configuração já não cumprir a condição alvo, as definições da configuração são removidas e o twin é modificado pela configuração de prioridade seguinte.

• Se um twin que atualmente executa esta configuração já não cumpre a condição alvo e não cumpre a condição alvo de quaisquer outras configurações, então as definições da configuração são removidas e não são feitas outras alterações no twin.

Para modificar uma configuração, use as seguintes etapas:

1. No portal do Azure, vá para o seu hub IoT.
2. No menu de serviço, em Gestão de Dispositivos, selecione Configurações + Implementações.
3. Selecione a configuração que deseja modificar.
4. Pode atualizar os seguintes campos: prioridade, métricas, condição alvo e etiquetas.
5. Selecione Guardar.
6. Siga os passos em Monitorizar uma configuração para acompanhar as alterações a serem implementadas.

Excluir uma configuração

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

1. No portal do Azure, vá para o seu hub IoT.
2. No menu de serviço, em Gestão de Dispositivos, selecione Configurações + Implementações.
3. Use a caixa de seleção para selecionar a configuração que você deseja excluir.
4. Selecione Eliminar.
5. Um prompt pede-te para confirmares a eliminação.

Pré-requisitos

• Uma assinatura ativa do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• Um hub IoT em sua assinatura do Azure. Se ainda não tem um hub, pode seguir os passos na secção Criar um hub IoT de Criar e gerir hubs IoT do Azure.

• Azure CLI no seu ambiente. No mínimo, a sua versão do Azure CLI deve ser 2.0.70 ou posterior. Usa az –-version para validar. Esta versão suporta os comandos de extensão Az e introduz o framework de comandos Knack.

• A extensão IoT para Azure CLI.

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 Azure IoT Hub identifica dispositivos usando etiquetas no gémeo do dispositivo, e identifica módulos usando etiquetas no gémeo dos módulos. Cada dispositivo ou módulo pode ter múltiplas etiquetas, e pode defini-las da forma que fizer sentido para a 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"
    }
},

Defina o conteúdo-alvo e as métricas

As consultas relativas ao conteúdo e às métricas de destino são especificadas como documentos JSON que descrevem as propriedades desejadas do dispositivo gémeo ou módulo gémeo a serem definidas e as propriedades reportadas que devem ser medidas. Para criar uma configuração automática usando Azure CLI, guarde localmente o conteúdo e as métricas de destino como ficheiros .txt. Usas os caminhos dos ficheiros numa secção posterior quando executas o comando para aplicar a configuração ao teu dispositivo.

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

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

As configurações automáticas de módulos comportam-se de forma semelhante, mas apontas 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 seleciona 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

Pode criar um máximo de 100 configurações automáticas em hubs IoT de nível padrão; 10 em hubs IoT de nível gratuito. Para saber mais, consulte quotas e restrições do IoT Hub.

Configura os dispositivos-alvo criando uma configuração que consiste no conteúdo e métricas alvo. 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 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 acompanhar a sua configuração. As etiquetas são pares de Nome, Valor que descrevem a sua implementação. Por exemplo, HostPlatform, Linux ou Version, 3.0.1

• -- conteúdo - JSON inline ou caminho de ficheiro para o conteúdo alvo a definir como propriedades gémeas desejadas.

• -- hub-name - Nome do hub IoT onde a configuração é criada. O hub deve estar na subscrição atual. Mudar para a subscrição desejada com o comando az account set -s [subscription name]

• -- condição alvo - Introduzir uma condição alvo para determinar quais os dispositivos ou módulos que são alvo desta configuração. Para a configuração automática do dispositivo, a condição baseia-se nas etiquetas gémeas do dispositivo ou nas propriedades desejadas do dispositivo gémeo e deve corresponder ao formato de expressão. Por exemplo, tags.environment='test' ou properties.desired.devicemodel='4000x'. Para a configuração automática dos módulos, a condição baseia-se nas etiquetas 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'.

• -- prioridade - Um inteiro positivo. Se duas ou mais configurações estiverem direcionadas para o mesmo dispositivo ou módulo, aplica-se a configuração com o valor numérico mais alto para a Prioridade.

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

Monitorar uma configuração

Use o seguinte comando para mostrar 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 onde existe a configuração. O hub deve estar na subscrição atual. Muda para a subscrição desejada com o comando az account set -s [subscription name].

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

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

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

• A sua métrica personalizada - Quaisquer métricas que tenha definido são métricas de utilizador.

Pode mostrar uma lista de IDs de dispositivos, IDs de módulos 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 implementação que existe no hub IoT.

• -- metric-id - O nome da métrica para a qual pretende ver a lista de identificadores de dispositivos ou de módulos, por exemplo, appliedCount.

• -- hub-name - Nome do hub IoT onde a implementação existe. O hub deve estar na subscrição atual. Muda para a subscrição desejada com o comando az account set -s [subscription name].

• -- Tipo métrico - O tipo métrico 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 replicam-se imediatamente para todos os dispositivos alvo.

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 twin que atualmente executa esta configuração já não cumprir a condição alvo, as definições da configuração são removidas e o twin é modificado pela configuração de prioridade seguinte.

• Se um twin que atualmente executa esta configuração já não cumpre a condição alvo e não cumpre a condição alvo de quaisquer outras configurações, então as definições da configuração são removidas e não são feitas outras alterações no twin.

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 onde existe a configuração. O hub deve estar na subscrição atual. Muda para a subscrição desejada com o comando az account set -s [subscription name].

• -- definir - Atualizar uma propriedade na configuração. Pode atualizar as seguintes propriedades:

  • Condição de destino - por exemplo targetCondition=tags.location.state='Oregon'

  • labels

  • priority

Excluir uma configuração

Quando apagas uma configuração, quaisquer duplas de dispositivos ou duplas de módulos assumem a sua próxima configuração de maior prioridade. Se os gémeos não cumprirem a condição alvo de qualquer outra configuração, então não são aplicadas outras configurações.

Use 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 onde existe a configuração. O hub deve estar na subscrição atual. Muda para a subscrição desejada com o comando az account set -s [subscription name].