Compartir a través de

Enriquecimientos para mensajes MQTT enrutados

  • Artículo

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, data ni data_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:

  1. En Azure Portal, vaya a su espacio de nombres.
  2. En Enrutamiento, active Habilitar enrutamiento.
  3. En tema de enrutamiento, seleccione el tema de Event Grid que ha creado donde se enrutarán todos los mensajes MQTT.
  4. En Enriquecimientos de mensajes, seleccione +Agregar enriquecimiento.
  5. Agregue hasta 20 pares clave-valor y seleccione su tipo correctamente.
  6. Seleccione Aplicar.

Screenshot showing the routing enrichment configuration through the portal.

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:

Conceptos: