共用方式為


裝置到雲端 IoT 中樞訊息的訊息擴充

訊息擴充是 IoT 中樞的一項功能,可在將訊息傳送至指定的端點之前,為訊息加上其他資訊的戳記。 使用訊息擴充的其中一個原因是要包含可用於簡化下游處理的資料。 例如,使用裝置對應項標籤擴充裝置遙測訊息,可減少客戶負載,以針對此資訊進行裝置對應項 API 呼叫。

Message enrichments flow

訊息擴充有三個主要元素:

  • 擴充名稱或金鑰

  • 應套用擴充的一或多個端點

索引鍵是字串。 索引鍵只能包含英數字元或下列特殊字元:連字號 (-)、底線 (_) 和句號 (.)。

可以是下列範例其中一項:

  • 任何靜態字串。 不允許動態值,例如條件、邏輯、作業和函式。 例如,如果您開發數個客戶所使用的 SaaS 應用程式,您可以將識別碼指派給每個客戶,並在應用程式中提供該識別碼。 當應用程式執行時,IoT 中樞會以客戶的識別碼替裝置遙測訊息加上戳記,讓每個客戶的訊息都能以不同的方式處理。

  • 傳送訊息的 IoT 中樞名稱。 此值為 $iothubname

  • 來自裝置對應項的資訊,例如其路徑。 範例為 $twin.tags.field$twin.tags.latitude

    注意

    目前,只有 $iothubname、$twin.tags、$twin.properties.desired 和 $twin.properties.reported 是訊息擴充支援的變數。 此外,擴充只支援基本類型。 訊息無法使用物件類型擴充。

訊息擴充會當作應用程式屬性新增到傳送至所選端點的訊息。

套用擴充

這些訊息可能來自 IoT 中樞訊息路由支援的任何資料來源,包括下列範例:

  • 裝置遙測,例如溫度或壓力
  • 裝置對應項變更通知 -- 裝置對應項中的變更
  • 裝置生命週期事件,例如建立或刪除裝置的時間

您可以將擴充新增至要前往至 IoT 中樞內建端點的訊息,或新增至要路由至自訂端點 (例如 Azure Blob 儲存體、服務匯流排佇列或服務匯流排主題) 的訊息。

您也可以先建立具有裝置遙測訊息類型的事件方格訂用帳戶,以將擴充新增至要發佈至事件方格的訊息。 根據此訂用帳戶,我們會在遙測的 Azure IoT 中樞中建立預設路由。 此單一路由可以處理您的所有事件方格訂用帳戶。 接著,您可以使用 IoT 中樞 [訊息路由] 區段的 [擴充訊息] 索引標籤來設定端點的擴充。 如需使用事件方格回應事件的相關資訊,請參閱 IoT 中樞和事件方格

每個端點都會套用擴充。 如果您指定五個擴充要針對特定端點加上戳記,則移至該端點的所有訊息都會以相同的五個擴充加上戳記。

可以使用下列方法來設定擴充:

方法 命令
入口網站 Azure 入口網站 請參閱訊息擴充教學課程
Azure CLI az iot hub message-enrichment
Azure PowerShell Add-AzIotHubMessageEnrichment

新增訊息擴充不會將延遲新增至訊息路由。

若要試用訊息擴充,請參閱訊息擴充教學課程

限制

  • 對於標準或基本層中的中樞,您可以為每個 IoT 中樞新增最多 10 個擴充。 對於免費層中的 IoT 中樞,您最多可以新增 2 個擴充。

  • 在某些情況下,如果您要擴充的訊息含有設為裝置對應項中標記或屬性的值,該值將會加上以指定裝置對應項路徑的戳記。 例如,如果擴充值設定為 $twin.tags.field,將為訊息加上字串 "$twin.tags.field" 戳記,而不是來自對應項中該欄位的值。 此行為會在下列情況中發生:

    • 您的 IoT 中樞位於基本層。 基本層 IoT 中樞不支援裝置對應項。

    • 您的 IoT 中樞位於標準層,但用於擴充值的裝置對應項路徑不存在。 例如,如果擴充值設定為 $twin.tags.location,而裝置對應項在標籤下沒有 location 屬性,將為訊息加上字串 "$twin.tags.location" 戳記。

    • 您的 IoT 中樞位於標準層,但用於擴充值的裝置對應項路徑會解析為物件,而不是簡單屬性。 例如,如果擴充值設定為 $twin.tags.location,而標籤下的 location 屬性是包含子屬性 (如 {"building": 43, "room": 503}) 的物件,則會為訊息加上字串 "$twin.tags.location" 戳記。

  • 裝置對應項的更新最多可能需要五分鐘的時間才會反映在對應的擴充值中。

  • 訊息大小總計 (包含擴充) 不能超過 256 KB。 如果訊息大小超過 256 KB,IoT 中樞將會捨棄訊息。 您可以使用 IoT 中樞計量,在捨棄訊息時識別和偵錯錯誤。 例如,您可以在路由計量中監視遙測訊息不相容 (d2c.telemetry.egress.invalid) 計量。 若要深入了解,請參閱監視 IoT 中樞

  • 訊息擴充不適用數位對應項變更事件。

  • 模組不會從其對應的裝置繼承對應項標記。 源自裝置模組的訊息擴充 (例如,來自 IoT Edge 模組),必須使用模組對應項上設定的對應項標籤。

定價

訊息擴充可以免費使用,不需額外付費。 目前,當您將訊息傳送至 IoT 中樞時,會向您收取費用。 即使該訊息傳送至多個端點,您仍只需針對該訊息支付一次費用。

下一步

如需將訊息路由至 IoT 中樞的詳細資訊,請參閱下列文章: