Enriquecimientos para mensajes MQTT enrutados
La compatibilidad con enriquecimientos permite agregar hasta 20 propiedades de clave-valor personalizadas a los mensajes antes de enviarlos al tema personalizado de Event Grid. Estos enriquecimientos le permiten:
- Agregar datos contextuales a los mensajes. Por ejemplo, enriquecer el mensaje con el nombre del cliente o el nombre del espacio de nombres podría proporcionar a los puntos de conexión información sobre el origen del mensaje.
- Reducir la carga de proceso en los puntos de conexión. Por ejemplo, enriquecer el mensaje con el indicador de formato de carga de la solicitud de publicación MQTT o el tipo de contenido informa a los puntos de conexión sobre cómo procesar la carga del mensaje sin probar primero varios analizadores.
- Filtrar los mensajes enrutados mediante suscripciones de eventos de Event Grid en función de los datos agregados. Por ejemplo, enriquecer un atributo de cliente permite filtrar los mensajes que se enrutarán al punto de conexión en función de los valores del atributo diferente.
Configuración
Clave de enriquecimiento:
La clave de enriquecimiento es una cadena que debe cumplir estos requisitos:
- Incluir solo caracteres alfanuméricos en minúsculas: solo (a-z) y (0-9).
- No debe ser
specversion,id,time,type,source,subject,datacontenttype,dataschema,datanidata_base64. - No debe empezar por
azsp. - No se debe duplicar.
- No debe tener más de 20 caracteres.
Valor de enriquecimiento:
El valor de enriquecimiento podría ser una cadena estática para enriquecimientos estáticos o uno de los valores admitidos que representan los atributos de cliente o las propiedades del mensaje MQTT para el enriquecimiento dinámico. Los valores de enriquecimiento no deben tener más de 128 caracteres. En la lista siguiente se incluyen los valores admitidos:
Atributos de cliente
- ${client.authenticationName}: el nombre del cliente de publicación.
- ${client.attributes.x}: un atributo del cliente de publicación, donde x es el nombre de la clave de atributo.
Propiedades de MQTT
- ${mqtt.message.userProperties.x}: propiedades de usuario en el paquete PUBLISH de MQTTv5, donde x es el nombre de clave de la propiedad de usuario.
- Type: cadena
- Use el siguiente formato de variable en su lugar si la propiedad de usuario incluye caracteres especiales ${mqtt.message.userProperties['x']}. Sigue teniendo que escapar un apóstrofo y una barra diagonal inversa de la siguiente manera: y "PN\t" se convierte en "PN\t".
- ${mqtt.message.topicName}: el tema del paquete PUBLISH de MQTT.
- Type: cadena
- ${mqtt.message.responseTopic}: el tema de respuesta del paquete PUBLISH de MQTTv5.
- Type: cadena
- ${mqtt.message.correlationData}: los datos de correlación del paquete PUBLISH de MQTTv5.
- Tipo: binario
- ${mqtt.message.pfi}: el indicador de formato de carga en el paquete PUBLISH de MQTTv5.
- Tipo: entero
Configuración de Azure Portal
Siga estos pasos para configurar los enriquecimientos de enrutamiento:
- En Azure Portal, vaya a su espacio de nombres.
- En Enrutamiento, active Habilitar enrutamiento.
- En tema de enrutamiento, seleccione el tema de Event Grid que ha creado donde se enrutarán todos los mensajes MQTT.
- En Enriquecimientos de mensajes, seleccione +Agregar enriquecimiento.
- Agregue hasta 20 pares clave-valor y seleccione su tipo correctamente.
- Seleccione Aplicar.
Para obtener más información sobre la configuración de enrutamiento, vaya a Enrutamiento de configuración de Azure Portal.
Configuración de la CLI de Azure
Use el comando y la carga durante la creación o actualización del espacio de nombres para configurar los enriquecimientos de enrutamiento:
az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --api-version 2023-06-01-preview --properties @./resources/NS.json
NS.json
{
"properties": {
"topicSpacesConfiguration": {
"state": "Enabled",
"routeTopicResourceId": "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/topics/<Event Grid Topic name>",
"routingEnrichments": {
"static": [
{
"key": "namespaceid",
"value": "123",
"valueType": "string"
}
],
"dynamic": [
{
"key": "clientname",
"value": "${client.authenticationName}"
},
{
"key": "clienttype",
"value": "${client.attributes.type}"
},
{
"key": "address",
"value": "${mqtt.message.userProperties['client.address']}"
},
{
"key": "region",
"value": "${mqtt.message.userProperties.location}"
},
{
"key": "mqtttopic",
"value": "${mqtt.message.topicName}"
},
{
"key": "mqttresponsetopic",
"value": "${mqtt.message.responseTopic}"
},
{
"key": "mqttcorrelationdata",
"value": "${mqtt.message.correlationData}"
},
{
"key": "mqttpfi",
"value": "${mqtt.message.pfi}"
}
]
}
}
},
"location": "eastus2euap",
"tags": {},
}
Para obtener más información sobre la configuración de enrutamiento, vaya a Enrutamiento de configuración de la CLI de Azure.
Salida de ejemplo
El siguiente CloudEvent es una salida de ejemplo de un mensaje MQTTv5 con PFI=0 después de aplicar la configuración de enriquecimiento anterior:
{
"specversion": "1.0",
"id": "9aeb0fdf-c01e-0131-0922-9eb54906e20", // unique id stamped by the service
"time": "2019-11-18T15:13:39.4589254Z", // timestamp when messages was received by the service
"type": "MQTT.EventPublished", // set type for all MQTT messages enveloped by the service
"source": "testnamespace", // namespace name
"subject": "campus/buildings/building17", // topic of the MQTT publish request
"namespaceid": "123", // static enrichment
"clientname": "client1", // dynamic enrichment of the name of the publishing client
"clienttype": "operator", // dynamic enrichment of an attribute of the publishing client
"address": "1 Microsoft Way, Redmond, WA 98052", // dynamic enrichment of a user property in the MQTT publish request
"region": "North America", // dynamic enrichment of another user property in the MQTT publish request
"mqtttopic": "campus/buildings/building17", // dynamic enrichment of the topic of the MQTT publish request
"mqttresponsetopic": "campus/buildings/building17/response", // dynamic enrichment of the response topic of the MQTT publish request
"mqttcorrelationdata": "cmVxdWVzdDE=", // dynamic enrichment of the correlation data of the MQTT publish request encoded in base64
"mqttpfi": 0, // dynamic enrichment of the payload format indicator of the MQTT publish request
"datacontenttype": "application/octet-stream", //content type of the MQTT publish request
"data_base64":
{
IlRlbXAiOiAiNzAiLAoiaHVtaWRpdHkiOiAiNDAiCg==
}
}
Administrar casos especiales:
- Propiedades de usuario o atributos de cliente no especificados: si un enriquecimiento dinámico apunta a una propiedad de usuario o atributo de cliente que no existe, el enriquecimiento incluirá la clave especificada con una cadena vacía para un valor. Por ejemplo,
emptyproperty: "". - Matrices: las matrices de los atributos de cliente y las propiedades de usuario duplicadas se transforman en una cadena separada por comas. Por ejemplo: si el atributo de cliente enriquecido se establece como "matriz": "valor1", "valor2", "valor3", la propiedad enriquecida resultante será
array:value1,value2,value3. Otro ejemplo: si la misma solicitud de publicación MQTT tiene las siguientes propiedades de usuario y "userproperty1": "value1", "userproperty1": "value2", la propiedad enriquecida resultante seráuserproperty1:value1,value2.
Siguientes pasos:
Para obtener más información sobre el enrutamiento, use los siguientes artículos:
Inicio rápido:
- Tutorial: Enrutamiento de mensajes MQTT a Azure Event Hubs mediante temas de espacio de nombres
- Tutorial: Enrutamiento de mensajes MQTT a Azure Functions mediante temas personalizados