MQTT Yönlendirilmiş İletiler için Zenginleştirmeler

Makale
03/19/2024

Zenginleştirme desteği, iletilerinize Event Grid özel konusuna gönderilmeden önce en fazla 20 özel anahtar-değer özelliği eklemenize olanak tanır. Bu zenginleştirmeler şunları yapmanızı sağlar:

İletilerinize bağlamsal veriler ekleyin. Örneğin, iletiyi istemcinin adı veya ad alanı adıyla zenginleştirmek, uç noktalara iletinin kaynağı hakkında bilgi sağlayabilir.
Uç noktalarda bilgi işlem yükünü azaltın. Örneğin, MQTT yayımlama isteğinin yük biçimi göstergesi veya içerik türüyle iletiyi zenginleştirmek, uç noktalara önce birden çok ayrıştırıcıyı denemeden iletinin yükünün nasıl işlendiği konusunda bilgi sağlar.
Eklenen verilere göre Event Grid olay abonelikleri aracılığıyla yönlendirilen iletilerinizi filtreleyin. Örneğin, bir istemci özniteliğini zenginleştirmek, uç noktaya yönlendirilecek iletileri farklı öznitelik değerlerine göre filtrelemenizi sağlar.

Yapılandırma

Zenginleştirme Anahtarı:

Zenginleştirme anahtarı, şu gereksinimlere uyması gereken bir dizedir:

Yalnızca küçük harf alfasayısalları dahil et: yalnızca (a-z) ve (0-9)
, , , , , type, , source, subject, datacontenttypedataschema, dataveya data_base64olmamalıdırspecversion. timeid
ile azspbaşlamamalıdır.
Çoğaltılmamalıdır.
20 karakterden uzun olmamalıdır.

Zenginleştirme Değeri:

Zenginleştirme değeri, statik zenginleştirmeler için statik bir dize veya istemci özniteliklerini veya dinamik zenginleştirme için MQTT ileti özelliklerini temsil eden desteklenen değerlerden biri olabilir. Zenginleştirme değerleri 128 karakterden uzun olmamalıdır. Aşağıdaki liste desteklenen değerleri içerir:

İstemci öznitelikleri

${client.authenticationName}: yayımlama istemcisinin adı.
${client.attributes.x}: yayımlama istemcisinin özniteliği; burada x, öznitelik anahtarı adıdır.

MQTT Özellikleri

${mqtt.message.userProperties.x}: MQTTv5 PUBLISH paketindeki kullanıcı özellikleri; burada x kullanıcı özelliği anahtar adıdır
- Tür: dize
- Kullanıcı özelliğiniz ${mqtt.message.userProperties['x']} özel karakterler içeriyorsa, bunun yerine aşağıdaki değişken biçimini kullanın. Yine de kesme işaretinden ve ters eğik çizgiden şu şekilde kurtulmanız gerekir: ve "PN\t" "PN\t" olur.
${mqtt.message.topicName}: MQTT PUBLISH paketindeki konu.
- Tür: dize
${mqtt.message.responseTopic}: MQTTv5 PUBLISH paketindeki yanıt konusu.
- Tür: dize
${mqtt.message.correlationData}: MQTTv5 PUBLISH paketindeki bağıntı verileri.
- Tür: ikili
${mqtt.message.pfi}: MQTTv5 PUBLISH paketindeki yük biçimi göstergesi.
- Tür: tamsayı

Azure portal yapılandırması

Yönlendirme zenginleştirmelerini yapılandırmak için aşağıdaki adımları kullanın:

Azure portalında ad alanınıza gidin.
Yönlendirme'nin altında Yönlendirmeyi etkinleştir'i işaretleyin.
Yönlendirme konusunun altında, oluşturduğunuz ve tüm MQTT iletilerinin yönlendirileceği Event Grid konusunu seçin.
İleti Zenginleştirmeleri'nin altında + Zenginleştirme Ekle'yi seçin.
En fazla 20 anahtar-değer çifti ekleyin ve türlerini uygun şekilde seçin.
Uygula’yı seçin.

Screenshot showing the routing enrichment configuration through the portal.

Yönlendirme yapılandırması hakkında daha fazla bilgi için Azure portal yapılandırmasını yönlendirme bölümüne gidin.

Azure CLI yapılandırması

Yönlendirme zenginleştirmelerini yapılandırmak için ad alanı oluşturma/güncelleştirme sırasında komutunu ve yükünü kullanın:

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

Yönlendirme yapılandırması hakkında daha fazla bilgi için Azure CLI yapılandırmasını yönlendirme bölümüne gidin.

Örnek Çıkış

Aşağıdaki CloudEvent, önceki zenginleştirme yapılandırmasını uyguladıktan sonra PFI=0 içeren bir MQTTv5 iletisinin örnek çıktısıdır:

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

Özel durumları işleme:

Belirtilmemiş istemci öznitelikleri/kullanıcı özellikleri: Var olmayan bir istemci özniteliğine/kullanıcı özelliğine işaret eden bir dinamik zenginleştirme varsa, zenginleştirme bir değer için boş dize içeren belirtilen anahtarı içerir. Örneğin, emptyproperty: "".
Diziler: İstemci özniteliklerindeki diziler ve yinelenen kullanıcı özellikleri virgülle ayrılmış bir dizeye dönüştürülür. Örneğin: Zenginleştirilmiş istemci özniteliği "dizi": "değer1", "değer2", "değer3" olarak ayarlanırsa, elde edilen zenginleştirilmiş özellik olacaktır array: value1,value2,value3. Başka bir örnek: Aynı MQTT yayımlama isteği şu kullanıcı özelliklerine > sahipse "userproperty1": "value1", "userproperty1": "value2", sonuçta zenginleştirilmiş özellik olacaktır userproperty1: value1,value2.

Sonraki adımlar:

Yönlendirme hakkında daha fazla bilgi edinmek için aşağıdaki makaleleri kullanın:

Aracılığıyla paylaş