MQTT 路由訊息的擴充

  • 發行項

擴充支援可讓您在訊息傳送至事件方格自定義主題之前，將最多 20 個自定義索引鍵/值屬性新增至訊息。 這些擴充可讓您：

  • 將內容相關數據新增至您的訊息。 例如，使用用戶端的名稱或命名空間名稱擴充訊息，可能會為端點提供訊息來源的相關信息。
  • 減少端點上的運算負載。 例如，使用 MQTT 發佈要求的承載格式指標來擴充訊息，或內容類型會通知端點如何在不先嘗試多個剖析器的情況下處理訊息的承載。
  • 根據新增的數據，透過 Event Grid 事件訂用帳戶篩選路由訊息。 例如，擴充用戶端屬性可讓您根據不同屬性值篩選要路由傳送至端點的訊息。

組態

擴充金鑰：

擴充金鑰是必須符合下列需求的字串：

  • 只包含小寫英數位元：僅限 （a-z） 和 （0-9）
  • 不得為 specversion、、、time、sourcetypesubjectdatacontenttype、dataschema、 data或 。data_base64id
  • 不得以 azsp開頭。
  • 不得重複。
  • 不得超過 20 個字元。

擴充值：

擴充值可以是靜態擴充的靜態字串，或代表動態擴充之客戶端屬性或 MQTT 訊息屬性的其中一個支援值。 擴充值不得超過 128 個字元。 下列清單包含支援的值：

用戶端屬性

  • ${client.authenticationName}：發佈客戶端的名稱。
  • ${client.attributes.x}：發行客戶端的屬性，其中 x 是屬性索引鍵名稱。

MQTT 屬性

  • ${mqtt.message.userProperties.x}： MQTTv5 PUBLISH 封包中的用戶屬性，其中 x 是使用者屬性密鑰名稱
    • 類型：string
    • 如果您的使用者屬性包含特殊字元 ${mqtt.message.userProperties['x']}，請改用下列變數格式。 您仍然需要逸出單引號和反斜杠，如下所示：且 “PN\t” 會變成 “PN\t”。
  • ${mqtt.message.topicName}：MQTT PUBLISH 封包中的主題。
    • 類型：string
  • ${mqtt.message.responseTopic}：MQTTv5 PUBLISH 封包中的響應主題。
    • 類型：string
  • ${mqtt.message.correlationData}：MQTTv5 PUBLISH 封包中的相互關聯數據。
    • 類型：binary
  • ${mqtt.message.pfi}：MQTTv5 PUBLISH 封包中的承載格式指標。
    • 類型：整數

Azure 入口網站 組態

使用下列步驟來設定路由擴充：

  1. 移至 Azure 入口網站 中的命名空間。
  2. 在 [路由] 底下，檢查 [啟用路由]。
  3. 在 [路由主題] 底下，選取您已建立的事件方格主題，其中會路由傳送所有 MQTT 訊息。
  4. 在 [訊息擴充] 底下，選取 [+ 新增擴充]。
  5. 最多新增 20 個機碼/值組，並適當地選取其類型。
  6. 選取套用。

Screenshot showing the routing enrichment configuration through the portal.

如需路由設定的詳細資訊，請移至路由 Azure 入口網站 組態。

Azure CLI 設定

在命名空間建立/更新期間使用 命令和承載來設定路由擴充：

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

如需路由設定的詳細資訊，請移至路由 Azure CLI 組態。

範例輸出

下列 CloudEvent 是套用先前擴充組態之後，具有 PFI=0 之 MQTTv5 訊息的範例輸出：

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

處理特殊案例：

  • 未指定的用戶端屬性/用戶屬性：如果動態擴充指向不存在的用戶端屬性/使用者屬性，擴充將會包含具有值之空字串的指定索引鍵。 例如： emptyproperty“”。
  • 陣列：客戶端屬性中的陣列和重複的使用者屬性會轉換成逗號分隔字串。 例如：如果擴充的用戶端屬性設定為 「array」： 「value1」、“value2”、“value3”，則產生的擴充屬性會是 array： value1,value2,value3。 另一個範例：如果相同的 MQTT 發佈要求具有下列使用者屬性 > “userproperty1”： “value1”、“userproperty1”： “value2”，產生的擴充屬性會是 userproperty1： value1,value2。

後續步驟：

使用下列文章深入瞭解路由：

快速入門：

概念：