Verrijkingen voor door MQTT gerouteerde berichten

Met de ondersteuning voor verrijkingen kunt u maximaal 20 aangepaste sleutelwaarde-eigenschappen toevoegen aan uw berichten voordat ze naar het aangepaste Event Grid-onderwerp worden verzonden. Met deze verrijkingen kunt u het volgende doen:

• Voeg contextuele gegevens toe aan uw berichten. Het verrijken van het bericht met de naam van de client of de naamruimtenaam kan bijvoorbeeld eindpunten bevatten over de bron van het bericht.
• Beperk de rekenbelasting op eindpunten. Als u het bericht bijvoorbeeld verrijkt met de payload-indelingsindicator van de MQTT-publicatieaanvraag of het inhoudstype informeert eindpunten over het verwerken van de nettolading van het bericht zonder eerst meerdere parsers uit te voeren.
• Filter uw gerouteerde berichten via Event Grid-gebeurtenisabonnementen op basis van de toegevoegde gegevens. Als u bijvoorbeeld een clientkenmerk verrijkt, kunt u de berichten filteren die naar het eindpunt worden gerouteerd op basis van de waarden van het verschillende kenmerk.

Configuratie

Verrijkingssleutel:

De verrijkingssleutel is een tekenreeks die moet voldoen aan deze vereisten:

• Alleen kleine alfanumerieke letters opnemen: alleen (a-z) en (0-9)
• Mag niet zijnspecversion, , id, time, type, , source, subject, datacontenttype, , dataschema, , of datadata_base64.
• Mag niet beginnen met azsp.
• Mag niet worden gedupliceerd.
• Mag niet langer zijn dan 20 tekens.

Verrijkingswaarde:

De verrijkingswaarde kan een statische tekenreeks zijn voor statische verrijkingen of een van de ondersteunde waarden die de clientkenmerken of de MQTT-berichteigenschappen voor dynamische verrijking vertegenwoordigen. Verrijkingswaarden mogen niet langer zijn dan 128 tekens. De volgende lijst bevat de ondersteunde waarden:

Clientkenmerken

• ${client.authenticationName}: de naam van de publicatieclient.
• ${client.attributes.x}: een kenmerk van de publicatieclient, waarbij x de naam van de kenmerksleutel is.

MQTT-eigenschappen

• ${mqtt.message.userProperties.x}: gebruikerseigenschappen in het MQTTv5 PUBLISH-pakket, waarbij x de naam van de gebruikerseigenschapssleutel is
  • Type: tekenreeks
  • Gebruik in plaats daarvan de volgende variabelenotatie als uw gebruikerseigenschap speciale tekens ${mqtt.message.userProperties['x']} bevat. U moet nog steeds een apostrof en backslash als volgt ontsnappen: en 'PN\t' wordt 'PN\t'.
• ${mqtt.message.topicName}: het onderwerp in het MQTT PUBLISH-pakket.
  • Type: tekenreeks
• ${mqtt.message.responseTopic}: het antwoordonderwerp in het MQTTv5 PUBLISH-pakket.
  • Type: tekenreeks
• ${mqtt.message.correlationData}: de correlatiegegevens in het MQTTv5 PUBLISH-pakket.
  • Type: binair
• ${mqtt.message.pfi}: de indicator voor de nettoladingnotatie in het MQTTv5 PUBLISH-pakket.
  • Type: geheel getal

Configuratie van Azure Portal

Gebruik de volgende stappen om routeringsverrijkingen te configureren:

1. Ga naar uw naamruimte in Azure Portal.
2. Schakel routering in onder Routering in.
3. Selecteer onder routeringsonderwerp het Event Grid-onderwerp dat u hebt gemaakt waar alle MQTT-berichten worden gerouteerd.
4. Selecteer onder Berichtverrijkingen de optie + Verrijking toevoegen.
5. Voeg maximaal 20 sleutel-waardeparen toe en selecteer het type op de juiste manier.
6. Selecteer Toepassen.

Voor meer informatie over de routeringsconfiguratie gaat u naar de configuratie van de Azure-portal voor routering.

Azure CLI-configuratie

Gebruik de opdracht en payload tijdens het maken/bijwerken van de naamruimte om routeringsverrijkingen te configureren:

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

Ga voor meer informatie over de routeringsconfiguratie naar de Azure CLI-configuratie routeren.

Voorbeelduitvoer

De volgende CloudEvent is een voorbeelduitvoer van een MQTTv5-bericht met PFI=0 nadat de vorige verrijkingsconfiguratie is toegepast:

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

Speciale gevallen verwerken:

• Niet-opgegeven clientkenmerken/gebruikerseigenschappen: als een dynamische verrijking verwijst naar een clientkenmerk/gebruikerseigenschap die niet bestaat, bevat de verrijking de opgegeven sleutel met een lege tekenreeks voor een waarde. Bijvoorbeeld emptyproperty: "".
• Matrices: matrices in clientkenmerken en dubbele gebruikerseigenschappen worden omgezet in een door komma's gescheiden tekenreeks. Bijvoorbeeld: als het verrijkte clientkenmerk is ingesteld op 'matrix': 'value1', 'value2', 'value3', is arrayde resulterende verrijkte eigenschap: . value1,value2,value3 Een ander voorbeeld: als dezelfde MQTT-publicatieaanvraag de volgende gebruikerseigenschappen > 'userproperty1' heeft: 'value1', 'userproperty1': 'value2', resulterende verrijkte eigenschap isuserproperty1: value1,value2

Volgende stappen:

Gebruik de volgende artikelen voor meer informatie over routering:

Quickstart:

• Zelfstudie: MQTT-berichten routeren naar Azure Event Hubs met behulp van naamruimteonderwerpen
• Zelfstudie: MQTT-berichten routeren naar Azure Functions met behulp van aangepaste onderwerpen

Concepten:

• Schema voor routeringsevenementen
• Routeringsfilters
• Routeringsverrijkingen