Obohacení pro směrované zprávy MQTT

Článek
03/15/2024

Podpora rozšiřování umožňuje přidat do zpráv až 20 vlastních vlastností klíč-hodnota před jejich odesláním do vlastního tématu Event Gridu. Tyto rozšíření umožňují:

Přidejte do zpráv kontextová data. Například rozšíření zprávy názvem klienta nebo názvem oboru názvů může poskytnout koncovým bodům informace o zdroji zprávy.
Snižte výpočetní zatížení koncových bodů. Například obohacení zprávy indikátorem formátu datové části žádosti o publikování MQTT nebo typu obsahu informuje koncové body, jak zpracovat datovou část zprávy, aniž byste nejprve vyzkoušeli více analyzátorů.
Filtrujte směrované zprávy prostřednictvím odběrů událostí Event Gridu na základě přidaných dat. Například rozšiřování atributu klienta umožňuje filtrovat zprávy, které se mají směrovat do koncového bodu na základě hodnot různých atributů.

Konfigurace

Klíč rozšiřování:

Klíč rozšiřování je řetězec, který musí splňovat tyto požadavky:

Zahrnout pouze malé alfanumerické znaky: pouze (a-z) a (0-9)
Nesmí být specversion, , , time, type, sourcesubjectdataschemadatacontenttype, datanebo data_base64. id
Nesmí začínat na azsp.
Nesmí být duplicitní.
Nesmí být delší než 20 znaků.

Hodnota rozšiřování:

Hodnota rozšiřování může být statický řetězec pro statické rozšiřování nebo jednu z podporovaných hodnot, které představují atributy klienta nebo vlastnosti zpráv MQTT pro dynamické rozšiřování. Hodnoty rozšiřování nesmí být delší než 128 znaků. Následující seznam obsahuje podporované hodnoty:

Atributy klienta

${client.authenticationName}: název klienta publikování.
${client.attributes.x}: atribut klienta publikování, kde x je název klíče atributu.

MQTT – vlastnosti

${mqtt.message.userProperties.x}: vlastnosti uživatele v paketu MQTTv5 PUBLISH, kde x je název klíče vlastnosti uživatele.
- Typ: řetězec
- Místo toho použijte následující formát proměnné, pokud vaše vlastnost uživatele obsahuje speciální znaky ${mqtt.message.userProperties['x']}. Stále potřebujete utéct apostrof a zpětné lomítko následujícím způsobem: a "PN\t" se změní na "PN\t".
${mqtt.message.topicName}: téma v paketu MQTT PUBLISH.
- Typ: řetězec
${mqtt.message.responseTopic}: téma odpovědi v paketu MQTTv5 PUBLISH.
- Typ: řetězec
${mqtt.message.correlationData}: data korelace v paketu MQTTv5 PUBLISH.
- Typ: binární
${mqtt.message.pfi}: indikátor formátu datové části v paketu MQTTv5 PUBLISH.
- Typ: celé číslo

Konfigurace webu Azure Portal

Ke konfiguraci rozšiřování směrování použijte následující kroky:

Na webu Azure Portal přejděte do svého oboru názvů.
V části Směrování zaškrtněte povolit směrování.
V části Téma směrování vyberte téma Event Gridu, které jste vytvořili, kde se budou směrovat všechny zprávy MQTT.
V části Obohacení zpráv vyberte + Přidat obohacení.
Přidejte až 20 párů klíč-hodnota a vyberte jejich typ odpovídajícím způsobem.
Vyberte Použít.

Screenshot showing the routing enrichment configuration through the portal.

Další informace o konfiguraci směrování najdete v tématu Směrování konfigurace webu Azure Portal.

Konfigurace Azure CLI

Ke konfiguraci rozšiřování směrování použijte příkaz a datovou část během vytváření nebo aktualizace oboru názvů:

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

Další informace o konfiguraci směrování najdete v tématu Směrování konfigurace Azure CLI.

Ukázkový výstup

Následující CloudEvent je ukázkový výstup zprávy MQTTv5 s PFI=0 po použití předchozí konfigurace rozšiřování:

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

Zpracování speciálních případů:

Nezadané atributy klienta / vlastnosti uživatele: Pokud dynamické rozšiřování odkazuje na atribut klienta nebo vlastnost uživatele, která neexistuje, bude rozšiřování zahrnovat zadaný klíč s prázdným řetězcem pro hodnotu. Například emptyproperty: "".
Pole: Pole v atributech klienta a duplicitní vlastnosti uživatele se transformují na řetězec oddělený čárkami. Například: Pokud je obohacený atribut klienta nastaven na "array": "value1", "value2", "value3", výsledná rozšířená vlastnost bude array: value1,value2,value3. Další příklad: Pokud má stejný požadavek na publikování MQTT následující vlastnosti > uživatele "userproperty1": "value1", "userproperty1": "value2", výsledná rozšířená vlastnost bude userproperty1: value1,value2.

Další kroky:

Další informace o směrování najdete v následujících článcích:

Sdílet prostřednictvím