Pengayaan untuk Pesan Rute MQTT

Artikel
03/15/2024

Dukungan pengayaan memungkinkan Anda menambahkan hingga 20 properti nilai kunci kustom ke pesan Anda sebelum dikirim ke topik kustom Event Grid. Pengayaan ini memungkinkan Anda untuk:

Tambahkan data kontekstual ke pesan Anda. Misalnya, memperkaya pesan dengan nama klien atau nama namespace layanan dapat menyediakan titik akhir dengan informasi tentang sumber pesan.
Kurangi beban komputasi pada titik akhir. Misalnya, memperkaya pesan dengan indikator format payload permintaan publikasi MQTT atau jenis konten menginformasikan titik akhir cara memproses payload pesan tanpa mencoba beberapa pengurai terlebih dahulu.
Filter pesan yang dirutekan melalui langganan peristiwa Event Grid berdasarkan data yang ditambahkan. Misalnya, memperkaya atribut klien memungkinkan Anda memfilter pesan yang akan dirutekan ke titik akhir berdasarkan nilai atribut yang berbeda.

Konfigurasi

Kunci Pengayaan:

Kunci pengayaan adalah string yang perlu mematuhi persyaratan ini:

Sertakan hanya alfanumerik huruf kecil: hanya (a-z) dan (0-9)
Tidak boleh specversion, , id, timetype, source, subject, datacontenttype, dataschema, data, , atau data_base64.
Tidak boleh dimulai dengan azsp.
Tidak boleh diduplikasi.
Tidak boleh lebih dari 20 karakter.

Nilai Pengayaan:

Nilai pengayaan bisa menjadi string statis untuk pengayaan statis atau salah satu nilai yang didukung yang mewakili atribut klien atau properti pesan MQTT untuk pengayaan dinamis. Nilai pengayaan tidak boleh lebih dari 128 karakter. Daftar berikut ini menyertakan nilai yang didukung:

Atribut klien

${client.authenticationName}: nama klien penerbitan.
${client.attributes.x}: atribut klien penerbitan, di mana x adalah nama kunci atribut.

Properti MQTT

${mqtt.message.userProperties.x}: properti pengguna dalam paket MQTTv5 PUBLISH, di mana x adalah nama kunci properti pengguna
- Jenis: string
- Gunakan format variabel berikut sebagai gantinya jika properti pengguna Anda menyertakan karakter khusus ${mqtt.message.userProperties['x']}. Anda masih perlu menghindari apostrof dan garis miring terbalik sebagai berikut: dan "PN\t" menjadi "PN\t".
${mqtt.message.topicName}: topik dalam paket MQTT PUBLISH.
- Jenis: string
${mqtt.message.responseTopic}: topik respons dalam paket MQTTv5 PUBLISH.
- Jenis: string
${mqtt.message.correlationData}: data korelasi dalam paket MQTTv5 PUBLISH.
- Jenis: biner
${mqtt.message.pfi}: indikator format payload dalam paket MQTTv5 PUBLISH.
- Jenis: bilangan bulat

Konfigurasi portal Microsoft Azure

Gunakan langkah-langkah berikut untuk mengonfigurasi pengayaan perutean:

Buka namespace Anda di portal Azure.
Di bawah Perutean, centang Aktifkan perutean.
Di bawah topik perutean, pilih topik Event Grid yang telah Anda buat di mana semua pesan MQTT akan dirutekan.
Di bawah Pengayaan Pesan, pilih + Tambahkan Pengayaan.
Tambahkan hingga 20 pasangan kunci-nilai dan pilih jenisnya dengan tepat.
Pilih Terapkan.

Screenshot showing the routing enrichment configuration through the portal.

Untuk informasi selengkapnya tentang konfigurasi perutean, buka Konfigurasi portal Azure perutean.

Konfigurasi CLI Azure

Gunakan perintah dan payload selama pembuatan/pembaruan namespace layanan untuk mengonfigurasi pengayaan perutean:

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

Untuk informasi selengkapnya tentang konfigurasi perutean, buka Perutean konfigurasi Azure CLI.

Output sampel

CloudEvent berikut adalah contoh output pesan MQTTv5 dengan PFI=0 setelah menerapkan konfigurasi pengayaan sebelumnya:

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

Menangani kasus khusus:

Atribut klien/properti pengguna yang tidak ditentukan: jika pengayaan dinamis menunjuk ke atribut klien/properti pengguna yang tidak ada, pengayaan akan menyertakan kunci yang ditentukan dengan string kosong untuk nilai. Misalnya, emptyproperty: "".
Array: Array dalam atribut klien dan properti pengguna duplikat diubah menjadi string yang dipisahkan koma. Misalnya: jika atribut klien yang diperkaya diatur menjadi "array": "value1", "value2", "value3", properti yang diperkaya yang dihasilkan adalah array: value1,value2,value3. Contoh lain: jika permintaan penerbitan MQTT yang sama memiliki properti > pengguna berikut "userproperty1": "value1", "userproperty1": "value2", properti yang diperkaya akan menjadi userproperty1: value1,value2.

Langkah berikutnya:

Gunakan artikel berikut untuk mempelajari selengkapnya tentang perutean:

Bagikan melalui