Preparar telemetria do Hub IoT para agentes e análises (pré-visualização)

O Hub IoT pode fornecer telemetria com contexto que ajuda aplicações, sistemas de análise e agentes a compreender qual dispositivo produziu uma leitura, qual contrato de dados a descreve e como interpretar a sua carga útil. Configure referências de tipo de dispositivo, referências de esquema de roteamento e formatos de mensagens de endpoint para transportar este contexto para serviços posteriores como o Microsoft Fabric.

Important

O contexto do tipo de dispositivo, a referência do esquema da mensagem e as capacidades padronizadas de carga útil de mensagens descritas neste artigo estão em pré-visualização. A ligação ADR e o endpoint de routing do Microsoft Fabric Eventstream são funcionalidades geralmente disponíveis que pode utilizar com esta pré-visualização.

Separe os três tipos de contexto

Concept Onde se enquadra Purpose
Referência do tipo de dispositivo Inscrição individual ou de grupo DPS; Registo de dispositivo ADR após provisionamento Identifica o tipo de dispositivo, como um Modelo de Coisa WoT, e fornece contexto de tipo de dispositivo para telemetria roteada.
Referência do esquema de dados Rota Hub IoT Associa mensagens encaminhadas ao contrato que descreve a sua carga útil original.
Formato da carga útil da mensagem Endpoint de routing do Hub IoT Entrega a carga útil original do dispositivo ou apresenta-a como uma observação padronizada.

Estas definições funcionam em conjunto. Por exemplo, um sensor de temperatura tem uma referência de tipo de dispositivo, as suas leituras de temperatura utilizam um esquema de dados versionado, e a sua rota entrega essas leituras ao Fabric num formato de observação padronizado. Um dispositivo pode emitir múltiplas formas de mensagem, e uma rota pode servir muitos dispositivos, por isso gere a definição do tipo de dispositivo e o esquema da mensagem como contratos separados.

Associar mensagens a um esquema

A referência do esquema de dados da rota corresponde a dataSchema no ARM e a --data-schema-ref no Azure IoT CLI. Descreve a carga útil original, não o invólucro de observação padronizado nem o envelope de transporte de destino.

Por exemplo, urn:example:schema:temperature-reading:1 pode identificar um esquema pertencente à sua aplicação. Use uma referência que os consumidores possam associar ao contrato e à versão apropriados.

Quando uma mensagem corresponde à rota, o Hub IoT inclui a referência do esquema configurada nos metadados da mensagem encaminhada. Uma aplicação recetora pode usar essa referência para selecionar o parser adequado, regras de validação ou modelo de análise. Para destinos Fabric, mantenha os metadados do esquema juntamente com o contexto CloudEvents ao processar o evento.

A referência identifica o contrato de carga útil; a validação da carga útil face a esse contrato pertence à fase de processamento do produtor ou a jusante. Mantenha a referência do esquema do payload original distinta do identificador de um formato de observação padronizado.

A referência é opcional. Nesta pré-visualização, o Hub IoT armazena-o como uma cadeia de caracteres; guardar uma rota não a valida contra um registo, e o routing não a desreferencia nem valida cada carga útil. A referência não altera a consulta de roteamento nem transforma a carga útil. O teste de consulta de rota não é validação de esquema nem um teste do formato entregue.

Deixa a referência sem definir se não tiveres uma. Use uma referência que descreva cada mensagem selecionada pela rota. Se as mensagens de telemetria e de falha usarem esquemas diferentes, utilize rotas separadas com condições e referências apropriadas. Para destinos que emitem CloudEvents, o atributo correspondente do envelope é dataschema. Não presuma que todos os destinos emitem CloudEvents.

Selecione o formato da mensagem do endpoint

O Formato da mensagem do endpoint corresponde a messagePayloadFormat no ARM e a --message-format na Azure IoT CLI.

Seleção Valor da API Comportamento da carga útil
Formato do dispositivo None Preserva a carga útil original do dispositivo; a codificação, os envelopes e o batching específicos do destino continuam a aplicar-se.
Padronizado DOObservationV1 Envolve o valor JSON original no formato de observação de Operações Digitais v1, identificado por com.do.telemetry.observation.v1.

Para o formato padronizado, publique um corpo UTF-8 válido contendo um valor JSON.

Por exemplo, temperature-sensor-01 publica esta carga útil do dispositivo:

{
  "deviceId": "temperature-sensor-01",
  "temperature": 21.5,
  "unit": "C"
}

No formato de dispositivo, o consumidor lê a carga útil original de acordo com a codificação e o envelope do destino. No formato padronizado, o valor original aparece sob payload.value num array de observação. A observação fornece uma estrutura consistente para o contexto do dispositivo, o momento do evento e a leitura.

Com Padronizado (DOObservationV1) selecionado, a mesma leitura é representada da seguinte forma. Este exemplo simplificado mostra a estrutura de observação e a carga útil original; o contexto adicional do dispositivo e os metadados de destino são omitidos.

[
  {
    "event_time": "2026-11-10T12:00:00Z",
    "event_kind": "measurement",
    "contract_version": "1.0",
    "schema_id": "com.do.telemetry.observation.v1",
    "schema_version": "1.0",
    "payload": {
      "value": {
        "deviceId": "temperature-sensor-01",
        "temperature": 21.5,
        "unit": "C"
      }
    }
  }
]

Os campos originais estão preservados no interior de payload.value. Por exemplo, um consumidor lê a temperatura do payload.value.temperature da primeira observação. O identificador com.do.telemetry.observation.v1 descreve essa estrutura, enquanto a referência do esquema de rota descreve a carga útil original de temperatura.

A saída padronizada não renomeia campos, não converte unidades, não achata objetos nem normaliza a carga interna de acordo com o seu esquema. Quando configurado, a referência de tipo de dispositivo ADR do dispositivo fornece o seu tipo semântico; a referência do esquema de dados de uma rota não atribui um tipo de dispositivo. Uma referência de tipo de dispositivo em falta produz campos de tipo nulo, em vez de impedir a saída da observação.

Important

O formato da mensagem pertence ao endpoint, não a uma rota individual. Alterá-la afeta todas as rotas que visam esse endpoint. Utilize endpoints separados se os consumidores precisarem de formatos diferentes e verifique a saída real antes de alterar um endpoint partilhado.

O Fabric utiliza uma representação CloudEvents para mensagens encaminhadas. O contexto CloudEvents identifica o evento, a sua origem e o seu sujeito. O formato de mensagem selecionado determina como os seus dados são representados. Preserve tanto o payload como os metadados associados ao definir transformações Eventstream e tabelas downstream.

O Fabric utiliza um envelope CloudEvents independentemente da escolha do formato da mensagem. Selecionar Standardized não ativa CloudEvents noutros tipos de endpoint, e o array de observação não é um lote CloudEvents.

Consulte Formatos de endpoint de roteamento e esquema de mensagens nos endpoints de roteamento.

Planeie referências de tipo de dispositivo DPS

Uma referência de tipo de dispositivo DPS identifica o tipo de dispositivo a ser provisionado, como o identificador de um Modelo de Coisa Web of Things (WoT). Em pré-visualização, pode definir a referência tanto para uma inscrição individual como para um grupo de inscrição. A referência aparece no registo do dispositivo ADR após o provisionamento. Os dispositivos provisionados através de um grupo de inscrição herdam a referência do tipo de dispositivo do grupo. O Hub IoT utiliza o contexto do dispositivo em ADR para enriquecer a telemetria roteada para interpretação a jusante.

Na experiência de registo DPS, abra Definições de dispositivo e introduza o valor em Referência de tipo de dispositivo. Na experiência de pré-visualização do dispositivo de registo ADR, inspecione o tipo de dispositivo na visão geral do dispositivo.

Para configuração da CLI, utilize as mesmas ferramentas de pré-visualização do guia do MQTT v5. A azure-iot versão 1.1.0b1 da extensão expõe --device-type-ref tanto comandos individuais como de grupo de inscrição e utiliza a versão 2026-11-02-previewda API DPS. A propriedade de serviço é deviceTypeRefs, um array; a opção CLI fornece uma referência.

Para uma inscrição existente, defina a referência usando o comando aplicável:

az iot dps enrollment update --dps-name "<dps-name>" --resource-group "<resource-group>" --enrollment-id "<individual-enrollment-id>" --device-type-ref "urn:example:thing-model:temperature-sensor:1"

az iot dps enrollment-group update --dps-name "<dps-name>" --resource-group "<resource-group>" --enrollment-id "<enrollment-group-id>" --device-type-ref "urn:example:thing-model:temperature-sensor:1"

O identificador é ilustrativo; utilize uma referência que as suas aplicações possam resolver para a definição de tipo de dispositivo pretendida. Leia o valor de inscrição armazenado antes de provisionar um dispositivo:

az iot dps enrollment show --dps-name "<dps-name>" --resource-group "<resource-group>" --enrollment-id "<individual-enrollment-id>" --query deviceTypeRefs

az iot dps enrollment-group show --dps-name "<dps-name>" --resource-group "<resource-group>" --enrollment-id "<enrollment-group-id>" --query deviceTypeRefs

Leia a propriedade do properties.deviceTypeRefs registo de dispositivo ADR para verificar a referência armazenada após o provisionamento:

az iot adr ns device show --namespace "<adr-namespace>" --resource-group "<resource-group>" --name "<adr-device-name>" --query properties.deviceTypeRefs

A referência do tipo de dispositivo fornece contexto descritivo. O DPS continua a utilizar as definições de autenticação e provisionamento da inscrição para estabelecer a identidade do dispositivo e a atribuição do hub.

Para conceitos de inscrição de DPS, consulte Gerir inscrições de dispositivos.

Exemplo: Preparar leituras de temperatura para Fabric

Utilize as três configurações em conjunto para dar aos consumidores posteriores uma interpretação consistente de uma leitura de temperatura:

  1. Defina a referência do tipo de dispositivo da inscrição DPS para urn:example:thing-model:temperature-sensor:1, e depois provisione o dispositivo.
  2. Defina a referência do esquema de dados da rota do Hub IoT para urn:example:schema:temperature-reading:1.
  3. Selecione Standardized (DOObservationV1) como o formato de mensagem do endpoint de routing Fabric.
  4. Publique uma leitura de temperatura que corresponda à condição da rota.
  5. No Fabric, processe a carga útil de observação juntamente com o contexto do dispositivo, metadados do esquema de rota e atributos CloudEvents.

Uma aplicação de análise pode usar a referência do esquema para interpretar temperature e unit, e a referência do tipo de dispositivo para compreender o dispositivo de origem. Um agente pode usar o mesmo contexto para selecionar uma análise apropriada ou resumir leituras entre dispositivos do mesmo tipo.

Verifique a prontidão com a aplicação receptora

Antes de ligar uma aplicação de análise ou um fluxo de trabalho de agente, envie uma mensagem de exemplo e confirme que a aplicação recetora pode:

  • Identifique o dispositivo de origem e o seu contexto de tipo de dispositivo.
  • Resolva a referência do esquema de rota ao contrato de payload pretendido.
  • Leia o payload original no formato de mensagem selecionado.
  • Retenha os metadados relevantes através de transformações e armazenamento.
  • Valide a leitura e trate as versões dos esquemas de forma consistente.

Conceda aos consumidores as permissões necessárias para ler os seus dados. Mantenha a interpretação de dados separada da autorização para realizar ações que alterem recursos.