Berikningar för MQTT-routade meddelanden

Artikel
03/16/2024

Med stöd för berikning kan du lägga till upp till 20 anpassade nyckelvärdesegenskaper i dina meddelanden innan de skickas till det anpassade event grid-ämnet. Med dessa berikanden kan du:

Lägg till kontextuella data i dina meddelanden. Om du till exempel utökar meddelandet med klientens namn eller namnområdesnamnet kan du ge slutpunkter information om källan till meddelandet.
Minska databehandlingsbelastningen på slutpunkter. Om du till exempel utökar meddelandet med MQTT-publiceringsbegärans formatindikator för nyttolast eller innehållstypen får slutpunkterna information om hur du bearbetar meddelandets nyttolast utan att prova flera parsers först.
Filtrera dina dirigerade meddelanden via Event Grid-händelseprenumerationer baserat på de data som lagts till. Om du till exempel utökar ett klientattribut kan du filtrera meddelandena så att de dirigeras till slutpunkten baserat på de olika attributvärdena.

Konfiguration

Berikningsnyckel:

Berikningsnyckeln är en sträng som måste uppfylla följande krav:

Inkludera endast alfanumeriska gemener: endast (a-z) och (0-9)
Får inte vara specversion, id, time, type, source, subject, datacontenttype, dataschema, dataeller data_base64.
Får inte börja med azsp.
Får inte dupliceras.
Får inte innehålla fler än 20 tecken.

Berikningsvärde:

Berikningsvärdet kan vara en statisk sträng för statiska berikningar eller ett av de värden som stöds som representerar klientattributen eller MQTT-meddelandeegenskaperna för dynamisk berikning. Berikningsvärden får inte innehålla mer än 128 tecken. Följande lista innehåller de värden som stöds:

Klientattribut

${client.authenticationName}: namnet på publiceringsklienten.
${client.attributes.x}: ett attribut för publiceringsklienten, där x är attributnyckelnamnet.

MQTT-egenskaper

${mqtt.message.userProperties.x}: användaregenskaper i MQTTv5 PUBLISH-paketet, där x är användarens egenskapsnyckelnamn
- Typ: sträng
- Använd följande variabelformat i stället om användaregenskapen innehåller specialtecken ${mqtt.message.userProperties['x']}. Du måste fortfarande undvika en apostrofer och ett omvänt snedstreck på följande sätt: och "PN\t" blir "PN\t".
${mqtt.message.topicName}: ämnet i MQTT PUBLISH-paketet.
- Typ: sträng
${mqtt.message.responseTopic}: svarsämnet i MQTTv5 PUBLISH-paketet.
- Typ: sträng
${mqtt.message.correlationData}: korrelationsdata i MQTTv5 PUBLISH-paketet.
- Typ: binär
${mqtt.message.pfi}: indikatorn för nyttolastformat i MQTTv5 PUBLISH-paketet.
- Typ: heltal

Konfiguration av Azure-portalen

Använd följande steg för att konfigurera routningsberikningar:

Gå till ditt namnområde i Azure-portalen.
Under Routning kontrollerar du Aktivera routning.
Under routningsavsnittet väljer du det Event Grid-ämne som du har skapat där alla MQTT-meddelanden ska dirigeras.
Under Meddelandeberikningar väljer du + Lägg till berikning.
Lägg till upp till 20 nyckel/värde-par och välj deras typ på rätt sätt.
Välj Använd.

Screenshot showing the routing enrichment configuration through the portal.

Mer information om routningskonfigurationen finns i Konfiguration av Routning av Azure-portalen.

Konfiguration av Azure CLI

Använd kommandot och nyttolasten när namnområdet skapas/uppdateras för att konfigurera routningsberikningar:

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

Mer information om routningskonfigurationen finns i Routning av Azure CLI-konfiguration.

Exempelutdata

Följande CloudEvent är ett exempel på utdata från ett MQTTv5-meddelande med PFI=0 efter att ha tillämpat den tidigare berikningskonfigurationen:

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

Hantering av specialfall:

Ospecificerade klientattribut/användaregenskaper: Om en dynamisk berikning pekar på ett klientattribut/en användaregenskap som inte finns innehåller berikningen den angivna nyckeln med en tom sträng för ett värde. Till exempel emptyproperty: "".
Matriser: Matriser i klientattribut och duplicerade användaregenskaper omvandlas till en kommaavgränsad sträng. Till exempel: om det berikade klientattributet är inställt på "array": "value1", "value2", "value3" blir arrayden resulterande berikade egenskapen : value1,value2,value3. Ett annat exempel: om samma MQTT-publiceringsbegäran har följande användaregenskaper > "userproperty1": "value1", "userproperty1": "value2", blir userproperty1den berikade egenskapen : value1,value2.

Nästa steg:

Använd följande artiklar för att lära dig mer om routning:

Dela via