Compartilhar via

O que os usuários do OSConfig precisam saber sobre as cadeias de ferramentas "simples desejadas/relatadas" versus "DTDL aprimorado"

  • Artigo

Ao ler documentos do OSConfig e experimentar cenários por meio de diferentes ferramentas, pode ser útil entender que, no ecossistema de IoT do Azure, há duas perspectivas para descrever o conteúdo gêmeo.

Perspectiva 1: Não desejado/relatado

As propriedades desejadas e relatadas compõem o modelo de objeto principal Hub IoT. A maioria das ferramentas e serviços usa essa perspectiva simples desejada/relatada. Por exemplo:

  • O serviço de consulta Hub IoT
  • O serviço Hub IoT Configurations
  • Os az iot hub module-twin comandos
  • As exibições de gêmeos do Hub Iot no portal do Azure
  • As exibições de gêmeo simples no IoT Explorer

A perspectiva clara desejada/relatada pode ser descrita como um documento JSON em que:

  1. O estado real (como configuração ou status atual) é relatado pelo código no dispositivo na properties.reported seção
  2. O estado desejado (como configurações do administrador), se houver, é adicionado por ferramentas de administrador na nuvem na properties.desired seção
  3. Se qualquer estado desejado tiver sido especificado do lado da nuvem, o código responsável no dispositivo reconhecerá o mesmo por meio de propriedades adicionais na properties.reported seção.

O exemplo a seguir é um trecho simplificado do módulo gêmeo OSConfig de um dispositivo no Hub IoT:

  1. O agente OSConfig no dispositivo sempre relata o nome do host atual como properties.reported.HostName.name
  2. Além disso, o administrador queria garantir um valor específico, portanto, no lado da nuvem, eles preencheram properties.desired.HostName.desiredName
  3. Em resposta a properties.desired.HostName.desiredName ser preenchido pelo administrador, o agente OSConfig no dispositivo reconhece o recebimento do mesmo que properties.reported.HostName.desiredName.

Captura de tela anotada mostrando as propriedades desejadas e relatadas

Perspectiva 2: Modelagem aprimorada da Linguagem de Definição de Gêmeo Digital (DTDL)

O DTDL (juntamente com padrões relacionados, como o Azure IoT Plug and Play [PnP]) permite que aplicativos e serviços antecipem, validem e contextualizem melhor o conteúdo gêmeo além do JSON simples. As ferramentas e os serviços que usam essa perspectiva aprimorada de DTDL incluem:

  • Os modos de exibição "Plug and Play" no IoT Explorer
  • O serviço gêmeos digitais do Azure

Uma exibição aprimorada de DTDL do conteúdo gêmeo acima pode ser descrita como:

  • Este dispositivo/módulo tem um componente chamado HostName que implementa a interface HOSTName do OSConfig

  • Dentro do componente/interface HostName , há uma propriedade somente leitura¹ chamada nome cujo valor deve ser uma cadeia de caracteres

  • Também dentro do componente HostName , há um property² gravável chamado desiredName cujo valor deve ser uma cadeia de caracteres

    ¹ No contexto DTDL, conforme aplicado a agentes de dispositivo como OSConfig, "somente leitura" significa que a propriedade é relatada pelo dispositivo, não definida (diretamente) pelo administrador na nuvem
    ² No contexto DTDL, conforme aplicado a agentes de dispositivo como OSConfig, "gravável" significa que a propriedade pode ser definida pelo administrador na nuvem e que, quando isso for recebido pelo dispositivo, haverá uma confirmação.

A captura de tela a seguir do IoT Explorer é um exemplo de uma ferramenta usando DTDL. Neste exemplo, o Gerenciador de IoT está permitindo que o administrador saiba que desiredName está disponível para ser definido em HostName. O administrador pode não saber que essa era uma opção, especialmente considerando que a properties.desired seção do gêmeo subjacente está em branco por padrão.

Captura de tela do modo de exibição avançado DTDL do IoT Explorer para propriedade gravável

Qual perspectiva a documentação do OSConfig descreve?

Na documentação de referência do OSConfig, é padrão descrever a perspectiva simples desejada/relatada. Quando o contexto adicional para ferramentas aprimoradas de DTDL é aplicável, essas informações são incluídas em parênteses.

Por exemplo, em CommandRunner: commandArguments (definido por administrador) os valores possíveis são descritos action como "1 (reinicialização), 2 (desligamento), 3 (RunCommand) ou 4 (refreshCommandStatus)". Em uma experiência simples desejada/relatada, como az iot hub module-twin show você verá os valores numéricos. Em uma experiência aprimorada de DTDL, como exibições de IoT Plug and Play do IoT Explorer, você verá os rótulos ("reinicialização", etc.)

Como fazer (ou uma ferramenta que estou usando, como o Gerenciador de IoT) encontrar os modelos DTDL (OSConfig) mais recentes?

No IoT Explorer, em > Configurações de IoT Plug and Play Inicial, escolha Adicionar um repositório configurável, com o seguinte caminho: raw.githubusercontent.com/Azure/azure-osconfig/main. Consulte a captura de tela a seguir para obter um exemplo.

Captura de tela do procedue descrito acima.

Se você quiser inspecionar os modelos diretamente, em vez de carregá-los no IoT Explorer, o URI será: https://github.com/Azure/azure-osconfig/tree/main/dtmi/osconfig.

Observação

Por que os modelos não estão localizados https://devicemodels.azure.com?

Versões mais antigas de modelos OSConfig foram publicadas em https://devicemodels.azure.com, mas (a partir desta gravação) não é possível publicar versões mais recentes lá. Em vez disso, o endereço GitHub acima deve ser usado.

Próximas etapas

Para obter uma visão geral dos cenários e funcionalidades do OSConfig, consulte:

Para obter exemplos práticos específicos, consulte: