Gerenciamento automático de dispositivos IoT e módulos

Pré-requisitos

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

• Um Hub IoT na assinatura do Azure. Se você ainda não tiver um hub, poderá seguir as etapas na seção Criar um hub IoT de Criar e gerenciar hubs IoT do Azure.

Implementar gêmeos digitais

As configurações automáticas de dispositivo exigem 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 do módulo exigem o uso de módulos gêmeos para sincronizar o estado entre a nuvem e os módulos. Para obter mais informações, consulte Entender e usar os módulos gêmeos no Hub IoT.

Use etiquetas para direcionar gêmeos

Antes de criar uma configuração, você deve especificar quais dispositivos ou módulos você deseja afetar. O Hub IoT do Azure identifica dispositivos usando marcas no dispositivo gêmeo e identifica módulos usando marcas no módulo gêmeo. Cada dispositivo ou módulo pode ter várias tags, e você pode defini-las de forma que faça sentido para a 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"
    }
},

Criar uma configuração

Você pode criar no máximo 100 configurações automáticas em hubs IoT de camada padrão; 10 em hubs IoT de camada gratuita. Para saber mais, confira as cotas e as restrições do Hub IoT.

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

2. No menu de serviço, em Gerenciamento de dispositivos, selecione Configurações + Implantações.

3. Selecione Adicionar e escolha a configuração do dispositivo gêmeo ou a configuração do módulo gêmeo 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. Insira um nome exclusivo para 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. Adicione rótulos para organizar e descrever sua configuração. Rótulos são pares chave-valor, como HostPlatform, Linux ou Version, 3.0.1.
3. Selecione Avançar para continuar.

Configurações de gêmeo

Defina o conteúdo nas propriedades desejadas do dispositivo gêmeo ou do módulo gêmeo de destino fornecendo duas entradas para cada configuração. Primeiro, especifique o caminho gêmeo, que aponta para a seção JSON dentro das propriedades desejadas do gêmeo para atualizar. Em seguida, insira o conteúdo JSON a ser inserido nesse local.

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

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

Também é possível 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 configuração gêmea para a propriedade de pressão.

Se duas ou mais configurações forem direcionadas ao mesmo caminho gêmeo, o conteúdo da configuração de prioridade mais alta se aplicará (a prioridade será definida na etapa 4).

Se você quiser remover uma propriedade existente, especifique o valor da propriedade para null.

Você pode adicionar mais configurações selecionando Adicionar Configuração do Dispositivo Gêmeo ou Adicionar Configuração do Módulo Gêmeo.

Dispositivos ou módulos de destino

Use a propriedade marcas dos gêmeos para direcionar os dispositivos ou módulos específicos que devem receber essa configuração. Também é possível direcionar propriedades reportadas de gêmeo.

As configurações automáticas de dispositivo só podem direcionar marcas do dispositivo gêmeo de destino e as configurações automáticas de módulo só podem ser direcionadas a marcas do módulo gêmeo.

Como várias configurações podem ter como destino o mesmo dispositivo ou módulo, cada configuração precisa de um número de prioridade. Se houver um conflito, a configuração com a prioridade mais alta ganhará.

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

2. Insira uma condição alvo para determinar quais dispositivos ou módulos são direcionados com essa configuração. A condição se baseia nas marcas do gêmeo ou propriedades reportadas do gêmeo e deve corresponder ao formato da expressão.

   • Para configuração automática do dispositivo, é possível especificar apenas a marca ou a propriedade relatada a ser direcionada. Por exemplo, tags.environment='test' ou properties.reported.chillerProperties.model='4000x'. Você pode especificar * para direcionar todos os dispositivos.

   • Para a configuração automática do módulo, use uma consulta para especificar marcas 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 curinga não pode ser usado para direcionar todos os módulos.

Métricas

As métricas fornecem contagens resumidas dos diversos estados que um dispositivo ou módulo pode reportar após aplicar o 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.

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

1. Insira um nome para Nome da Métrica.

2. Insira uma consulta para Critérios de Métrica. A consulta é baseada nas propriedades reportadas de dispositivo gêmeo. 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 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 relatar os módulos configurados, selecione moduleId entre devices.modules. Por exemplo:

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

Revisar Configuração

Examine as informações 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 hub IoT.

2. No menu de serviço, em Gerenciamento de dispositivos, selecione Configurações + Implantações.

3. Inspecione a lista de configuração. 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 direcionados.

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

   • Tempo de criação – o timestamp de quando a configuração foi criada. Esse carimbo de data/hora é usado para desempate quando duas configurações têm a mesma prioridade.

   • Métricas do sistema – métricas calculadas pelo Hub IoT e que não podem ser personalizadas pelos desenvolvedores. Destino: especifica o número de dispositivos gêmeos que correspondem à condição de destino. Aplica-se: especifica o número de dispositivos gêmeos que são modificados pela configuração, o que pode incluir modificações parciais se uma configuração separada de prioridade mais alta também fez alterações.

   • Métricas personalizadas: métricas que são especificadas pelo desenvolvedor como consultas em propriedades reportadas do gêmeo. 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 de destino ou módulos de destino – os dispositivos ou módulos que correspondem à condição de destino.

   • Métricas – uma lista de métricas do sistema e métricas personalizadas. Você pode exibir uma lista de dispositivos ou módulos que são contados para cada métrica selecionando a métrica na lista suspensa e selecionando Exibir Dispositivos ou Exibir Módulos.

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

   • Configurações do Dispositivo Gêmeo ou Configurações do Módulo Gêmeo – as configurações de gêmeo 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, ocorrerão as seguintes atualizações:

• Se um gêmeo não atender à condição de destino antiga, mas atender à nova condição de destino e essa configuração for a prioridade mais alta para esse gêmeo, essa configuração será aplicada.

• Se um gêmeo atualmente executando essa configuração não atender à 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.

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

1. No portal do Azure, vá para o hub IoT.
2. No menu de serviço, em Gerenciamento de dispositivos, selecione Configurações + Implantações.
3. Selecione a configuração que você deseja modificar.
4. Você pode fazer atualizações nos seguintes campos: prioridade, métricas, condição de destino e rótulos.
5. Clique em Salvar.
6. Siga as etapas em Monitorar uma configuração para ver enquanto as alterações são implementadas.

Excluir uma configuração

Quando você exclui uma configuração, todos os dispositivos gêmeos assumem a próxima configuração de prioridade mais alta. Se os dispositivos gêmeos não atenderem à condição de destino de qualquer outra configuração, nenhuma outra configuração será aplicada.

1. No portal do Azure, vá para o hub IoT.
2. No menu de serviço, em Gerenciamento de dispositivos, selecione Configurações + Implantações.
3. Use a caixa de seleção para selecionar a configuração que você deseja excluir.
4. Selecione Excluir.
5. Um prompt solicita que você confirme a exclusão.

Pré-requisitos

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

• Um Hub IoT na assinatura do Azure. Se você ainda não tiver um hub, poderá seguir as etapas na seção Criar um hub IoT de Criar e gerenciar hubs IoT do Azure.

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

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

Implementar gêmeos digitais

As configurações automáticas de dispositivo exigem 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 do módulo exigem o uso de módulos gêmeos para sincronizar o estado entre a nuvem e os módulos. Para obter mais informações, consulte Entender e usar os módulos gêmeos no Hub IoT.

Use etiquetas para direcionar gêmeos

Antes de criar uma configuração, você deve especificar quais dispositivos ou módulos você deseja afetar. O Hub IoT do Azure identifica dispositivos e usa marcas no dispositivo gêmeo e identifica módulos usando marcas no módulo gêmeo. Cada dispositivo ou módulo pode ter várias etiquetas, e você pode defini-las da forma que fizer 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 o conteúdo e as métricas alvo

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 de destino e as métricas localmente como arquivos .txt. Use os caminhos de arquivo em uma seção posterior ao 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 semelhante, mas você direciona moduleContent em vez de deviceContent.

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

Aqui estão exemplos de consultas de métrica:

{
  "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

Você pode criar no máximo 100 configurações automáticas em hubs IoT de camada padrão; 10 em hubs IoT de camada gratuita. Para saber mais, confira cotas e limitações do Hub IoT.

Você configura 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 criada no hub IoT. Dê à sua configuração um nome exclusivo com até 128 caracteres. Letras minúsculas e os seguintes caracteres especiais são permitidos: -+%_*!'. Não são permitidos espaços.

• -- rótulos – Adicione rótulos para ajudar a acompanhar sua configuração. Rótulos são pares de Nome e Valor que descrevem sua 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.

• -- nome do hub – nome do hub IoT no qual a configuração é criada. O hub deve estar na assinatura atual. Alternar para a assinatura desejada com o comando az account set -s [subscription name]

• -- condição de destino – insira uma condição de destino para determinar quais dispositivos ou módulos são direcionados com essa configuração. Para a configuração automática do dispositivo, a condição é baseada em marcas de dispositivo gêmeo ou 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 do módulo, a condição é baseada em marcas de módulo gêmeo ou 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 forem direcionadas ao mesmo dispositivo ou módulo, a configuração com o valor numérico mais alto para Prioridade será aplicada.

• -- metrics: caminho para as consultas de métricas. As métricas fornecem uma contagem resumida dos estados variados que um dispositivo ou módulo pode relatar após a aplicação do conteúdo da 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.

• -- nome do hub – 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 de métricas 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 destino.

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

• Sua métrica personalizada – todas as métricas definidas são métricas do 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.

• -- nome do hub – 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].

• -- tipo de métrica – 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, ocorrerão as seguintes atualizações:

• Se um gêmeo não atender à condição de destino antiga, mas atender à nova condição de destino e essa configuração for a prioridade mais alta para esse gêmeo, essa configuração será aplicada.

• Se um gêmeo atualmente executando essa configuração não atender à 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.

• -- nome do hub – 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 - Atualizar uma propriedade na configuração. Você pode atualizar as seguintes propriedades:

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

  • labels

  • priority

Excluir uma configuração

Quando você exclui uma configuração, todos os dispositivos gêmeos ou módulos gêmeos assumem a 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.

• -- nome do hub – 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].