Enrichissements pour les messages routés MQTT

Article
04/22/2024

La prise en charge des enrichissements vous permet d’ajouter jusqu’à 20 propriétés clé-valeur personnalisées à vos messages avant qu’ils ne soient envoyés à la rubrique personnalisée Event Grid. Ces enrichissements vous permettent de :

Ajouter des données contextuelles à vos messages. Par exemple, l’enrichissement du message avec le nom du client ou le nom de l’espace de noms peut fournir aux points de terminaison des informations sur la source du message.
Réduire la charge de calcul sur les points de terminaison. Par exemple, l’enrichissement du message avec l’indicateur de format de charge utile de la demande de publication MQTT ou le type de contenu indique aux points de terminaison comment traiter la charge utile du message sans essayer d’abord plusieurs analyseurs.
Filtrer vos messages routés via les abonnements aux événements Event Grid en fonction des données ajoutées. Par exemple, l’enrichissement d’un attribut client vous permet de filtrer les messages à acheminer vers le point de terminaison en fonction des valeurs des différents attributs.

Configuration

Clé d’enrichissement :

La clé d’enrichissement est une chaîne de caractères qui doit respecter les conditions suivantes :

Inclure uniquement les alphanumériques minuscules : uniquement (a-z) et (0-9)
Ne doit pas être specversion, id, time, type, source, subject, datacontenttype, dataschema, data, ou data_base64.
Ne doit pas commencer par azsp.
Ne doit pas être dupliqué.
Ne doit pas dépasser 20 caractères.

Valeur d’enrichissement :

La valeur d’enrichissement peut être une chaîne statique pour les enrichissements statiques ou l’une des valeurs prises en charge qui représentent les attributs client ou les propriétés de message MQTT pour l’enrichissement dynamique. Les valeurs d’enrichissement ne doivent pas dépasser 128 caractères. La liste suivante inclut les valeurs prises en charge :

Attributs client

${client.authenticationName} : nom du client de publication.
${client.attributes.x} : attribut du client de publication, où x est le nom de clé d’attribut.

Propriétés MQTT

${mqtt.message.userProperties.x} : propriétés utilisateur dans le paquet MQTTv5 PUBLISH, où x est le nom de clé de la propriété utilisateur
- Type: string
- Utilisez plutôt le format de variable suivant si votre propriété utilisateur inclut des caractères spéciaux ${mqtt.message.userProperties['x']}. Vous devez toujours échapper une apostrophe et une barre oblique inverse comme suit : et « PN\t » devient « PN\t ».
${mqtt.message.topicName} : rubrique dans le paquet MQTT PUBLISH.
- Type: string
${mqtt.message.responseTopic} : rubrique de réponse dans le paquet MQTTv5 PUBLISH.
- Type: string
${mqtt.message.correlationData} : données de corrélation dans le paquet MQTTv5 PUBLISH.
- Type : binaire
${mqtt.message.pfi} : indicateur de format de charge utile dans le paquet MQTTv5 PUBLISH.
- Type : entier

Configuration du portail Azure

Suivez les étapes suivantes pour configurer les enrichissements de routage :

Accédez à votre espace de noms dans le Portail Azure.
Sous Routage, cochez Activer le routage.
Sous la rubrique de routage, sélectionnez la rubrique Event Grid que vous avez créée où tous les messages MQTT seront acheminés.
Sous Enrichissements de messages, sélectionnez +Ajouter un enrichissement.
Ajoutez jusqu’à 20 paires clé-valeur et sélectionnez leur type de manière appropriée.
Sélectionnez Appliquer.

Screenshot showing the routing enrichment configuration through the portal.

Pour plus d’informations sur la configuration du routage, accédez à Configuration du routage Portail Azure.

Configuration d’Azure CLI

Utilisez la commande et la charge utile lors de la création/mise à jour de l’espace de noms pour configurer les enrichissements de routage :

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": {},
}

Pour plus d’informations sur la configuration du routage, accédez à Configuration du routage Azure CLI.

Exemple de sortie

L’événement CloudEvent suivant est un exemple de sortie d’un message MQTTv5 avec PFI=0 après l’application de la configuration d’enrichissement précédente :

{
    "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==
	}
}

Gestion des cas spéciaux :

Attributs client/propriétés utilisateur non spécifiés : si un enrichissement dynamique pointe vers un attribut client/propriété utilisateur qui n’existe pas, l’enrichissement inclut la clé spécifiée avec une chaîne vide pour une valeur. Par exemple, emptyproperty : «».
Tableaux : les tableaux dans les attributs client et les propriétés utilisateur en double sont transformés en chaîne séparée par des virgules. Par exemple : si l’attribut client enrichi est défini sur « array » : « value1 », « value2 », « value3 », la propriété enrichie résultante sera array : value1,value2,value3. Autre exemple : si la même demande de publication MQTT a les propriétés utilisateur > suivantes « userproperty1 » : « value1 », « userproperty1 » : « value2 », la propriété enrichie résultante sera userproperty1 : value1,value2.

Étapes suivantes :

Pour en savoir plus sur le routage, lisez les articles suivants :

Partage via