Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
IoT Hub puede ofrecer telemetría con contexto que ayuda a aplicaciones, sistemas de análisis y agentes a entender qué dispositivo produjo una lectura, qué contrato de datos la describe y cómo interpretar su carga útil. Configura referencias de tipo de dispositivo, referencias de esquema de ruta y formatos de mensajes de endpoint para llevar este contexto a servicios de destino como Microsoft Fabric.
Importante
El contexto del tipo de dispositivo, la referencia del esquema de mensajes y las capacidades estandarizadas de carga útil de mensajes descritas en este artículo están en vista previa. La vinculación ADR y el endpoint de enrutamiento de Microsoft Fabric Eventstream son capacidades generalmente disponibles que puedes utilizar con esta vista previa.
Separa los tres tipos de contexto
| Concepto | Dónde pertenece | Purpose |
|---|---|---|
| Referencia del tipo de dispositivo | Inscripción individual o grupal de DPS; Registro del dispositivo ADR tras la aprovisionación | Identifica el tipo de dispositivo, como un Modelo de Cosa WoT, y proporciona contexto de tipo de dispositivo para la telemetría enrutada. |
| Referencia del esquema de datos | Ruta IoT Hub | Asocia los mensajes enrutados con el contrato que describe su carga útil original. |
| Formato de carga útil del mensaje | Endpoint de enrutamiento de IoT Hub | Entrega la carga útil original del dispositivo o la presenta como una observación estandarizada. |
Estos ajustes funcionan conjuntamente. Por ejemplo, un sensor de temperatura tiene una referencia de tipo de dispositivo, sus lecturas de temperatura utilizan un esquema de datos versionado, y su ruta entrega esas lecturas a Fabric en un formato de observación estandarizado. Un dispositivo puede emitir múltiples formas de mensaje, y una ruta puede servir a muchos dispositivos, así que gestiona la definición del tipo de dispositivo y el esquema de mensajes como contratos separados.
Asociar mensajes con un esquema
La referencia del esquema de datos de la ruta corresponde a dataSchema en ARM y --data-schema-ref en la CLI de Azure IoT. Describe la carga útil original, no el envoltorio de observación estandarizado ni el envolvente de transporte de destino.
Por ejemplo, urn:example:schema:temperature-reading:1 puede identificar un esquema propiedad de tu aplicación. Utiliza una referencia que los consumidores puedan resolver al contrato y la versión adecuados.
Cuando un mensaje coincide con la ruta, IoT Hub incluye la referencia del esquema configurado en los metadatos del mensaje enrutado. Una aplicación receptora puede utilizar esa referencia para seleccionar el analizador adecuado, las reglas de validación o el modelo analítico adecuado. Para destinos Fabric, conserva los metadatos del esquema junto al contexto CloudEvents al procesar el evento.
La referencia identifica el contrato de carga útil; la validación de la carga útil frente a ese contrato corresponde al productor o a la etapa de procesamiento posterior. Mantén la referencia del esquema de carga útil original distinta del identificador de un formato de observación estandarizado.
La referencia es opcional. En esta vista previa, IoT Hub lo almacena como una cadena de texto; guardar una ruta no la valida frente a un registro, y el enrutamiento no la desreferencia ni valida cada carga útil. La referencia no cambia la consulta de enrutamiento ni transforma la carga útil. La prueba de consulta de ruta no es validación de esquema ni una prueba del formato entregado.
Deja la referencia sin ajustar si no tienes una. Utiliza una referencia que describa cada mensaje seleccionado por la ruta. Si los mensajes de telemetría y fallos utilizan esquemas diferentes, utilice rutas separadas con condiciones y referencias adecuadas.
Para destinos que emiten CloudEvents, el atributo correspondiente del sobre es dataschema. No des por hecho que cada destino emite CloudEvents.
Seleccione el formato de mensaje del endpoint
El formato de mensaje del endpoint se corresponde a messagePayloadFormat en ARM y --message-format en la CLI de Azure IoT.
| Selection | Valor de API | Comportamiento de la carga útil |
|---|---|---|
| Formato de dispositivo | None |
Conserva la carga útil original del dispositivo; la codificación específica de destino, los envolventes y el procesamiento por lotes siguen aplicándose. |
| Estandarizado | DOObservationV1 |
Envuelve el valor JSON original en el formato de observación de Operaciones Digitales v1, identificado por com.do.telemetry.observation.v1. |
Para el formato estandarizado, publique un cuerpo UTF-8 válido que contenga un valor JSON.
Por ejemplo, temperature-sensor-01 publica esta carga útil del dispositivo:
{
"deviceId": "temperature-sensor-01",
"temperature": 21.5,
"unit": "C"
}
En formato de dispositivo, el consumidor lee la carga útil original según la codificación y la envoltura del destino. En formato estandarizado, el valor original aparece bajo payload.value en un array de observación. La observación proporciona una estructura consistente para el contexto del dispositivo, el momento del evento y la lectura.
Con Estandarizado (DOObservationV1) seleccionado, la misma lectura se representa de la siguiente manera. Este ejemplo simplificado muestra la estructura de observación y la carga útil original; se omiten metadatos adicionales de contexto del dispositivo y destino.
[
{
"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"
}
}
}
]
Los campos originales se conservan en el interior de payload.value. Por ejemplo, un consumidor lee la temperatura a partir del payload.value.temperature de la primera observación.
El identificador com.do.telemetry.observation.v1 describe esa estructura, mientras que la referencia del esquema de ruta describe la carga útil original de temperatura.
La salida estandarizada no renombra campos, no convierte unidades, no aplana objetos ni normaliza la carga interna contra tu esquema. Cuando está configurado, la referencia de tipo de dispositivo ADR del dispositivo proporciona su tipo semántico; la referencia del esquema de datos de una ruta no asigna un tipo de dispositivo. Una referencia de tipo de dispositivo ausente produce campos de tipo nulo, en lugar de impedir la salida de la observación.
Importante
El formato del mensaje pertenece al endpoint, no a una ruta individual. Cambiarlo afecta a todas las rutas que apuntan a ese endpoint. Utilice puntos finales separados si los consumidores necesitan formatos diferentes y verifique la salida real antes de cambiar un punto final compartido.
Fabric utiliza una representación CloudEvents para mensajes enrutados. El contexto CloudEvents identifica el evento, su fuente y su sujeto. El formato de mensaje seleccionado determina cómo se representan sus datos. Conserve tanto la carga útil como sus metadatos asociados al definir transformaciones Eventstream y tablas de destino.
Fabric utiliza un sobre CloudEvents independientemente de la elección de formato del mensaje. Seleccionar Estandarizado no habilita CloudEvents en otros tipos de endpoint, y el array de observación no es un lote CloudEvents.
Consulte Formatos de enrutamiento de endpoints y esquema de mensajes en endpoints de enrutamiento.
Planificar referencias de tipo de dispositivo DPS
Una referencia de tipo de dispositivo DPS identifica el tipo de dispositivo que se está provisionando, como el identificador de un Thing Model de Web of Things (WoT). En vista previa, puedes establecer la referencia tanto para una inscripción individual como para un grupo de inscripción. La referencia aparece en el registro del dispositivo ADR tras el aprovisionamiento. Los dispositivos provisionados a través de un grupo de inscripción heredan la referencia del tipo de dispositivo del grupo. IoT Hub utiliza el contexto del dispositivo en ADR para enriquecer la telemetría enrutada para la interpretación posterior.
En la experiencia de inscripción de DPS, abra Configuración del dispositivo e introduzca el valor en Referencia de tipo de dispositivo. En la vista previa de la experiencia del dispositivo del registro ADR, inspeccione Tipo de dispositivo en la vista general del dispositivo.
Para la configuración de la CLI, utilice las mismas herramientas de vista previa que en la guía MQTT v5.
La azure-iot versión 1.1.0b1 de la extensión expone --device-type-ref tanto comandos de inscripción individuales como de grupo y utiliza la versión 2026-11-02-previewde la API DPS. La propiedad de servicio es deviceTypeRefs, un array; la opción CLI proporciona una referencia.
Para una inscripción existente, establece la referencia usando el comando correspondiente:
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"
El identificador es ilustrativo; utilice una referencia que sus aplicaciones puedan resolver a la definición de tipo de dispositivo prevista. Lee el valor de inscripción almacenado antes de provisionar un 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
Lea la propiedad del properties.deviceTypeRefs registro de dispositivo ADR para verificar la referencia almacenada tras el aprovisionamiento:
az iot adr ns device show --namespace "<adr-namespace>" --resource-group "<resource-group>" --name "<adr-device-name>" --query properties.deviceTypeRefs
La referencia de tipo de dispositivo proporciona contexto descriptivo. DPS continúa utilizando los ajustes de autenticación y aprovisionamiento de la inscripción para establecer la identidad del dispositivo y la asignación del hub.
Para los conceptos de inscripción de DPS, consulte Gestionar las inscripciones de dispositivos.
Ejemplo: Preparar lecturas de temperatura para Fabric
Utilice los tres ajustes juntos para ofrecer a los consumidores posteriores una interpretación consistente de una lectura de temperatura:
- Establece la referencia del tipo de dispositivo de la inscripción DPS en
urn:example:thing-model:temperature-sensor:1, y luego provisiona el dispositivo. - Establezca la referencia del esquema de datos de la ruta de IoT Hub en
urn:example:schema:temperature-reading:1. - Seleccione Estandarizado (
DOObservationV1) como formato de mensaje del endpoint de enrutamiento de Fabric. - Publique una lectura de temperatura que coincida con la condición de la ruta.
- En Fabric, procesa la carga útil de observación junto con el contexto del dispositivo, los metadatos del esquema de ruta y los atributos CloudEvents.
Una aplicación de analítica puede utilizar la referencia de esquema para interpretar temperature y unit, y la referencia del tipo de dispositivo para entender el dispositivo de origen. Un agente puede utilizar el mismo contexto para seleccionar un análisis adecuado o resumir lecturas entre dispositivos del mismo tipo.
Verifique la preparación con la aplicación receptora
Antes de conectar una aplicación de analítica o un flujo de trabajo de agente, envíe un mensaje de ejemplo y confirme que la aplicación receptora puede:
- Identifique el dispositivo de origen y su contexto de tipo de dispositivo.
- Resuelva la referencia del esquema de ruta al contrato de carga útil previsto.
- Lea la carga útil original en el formato de mensaje seleccionado.
- Conservar los metadatos relevantes mediante transformaciones y almacenamiento.
- Valida la lectura y maneja las versiones del esquema de forma coherente.
Otorgue a los consumidores los permisos necesarios para leer sus datos. Mantén la interpretación de los datos separada de la autorización para realizar acciones que modifiquen recursos.