在資料流程圖中使用視窗轉換彙總資料

視窗轉換會將收到的訊息分組,並在視窗關閉時產生一個包含彙總值的單一輸出訊息。 你不必逐一轉發每一次讀數,而是可以計算統計數據,如平均值、最小值或計數,並將一個合併結果送往下游。

視窗會根據持續時間、計數、記憶體或觸發條件而關閉。 這些視窗為不重疊的輪轉視窗;不提供滑動視窗。

關於資料流程圖的概述以及在管線中轉換的組合方式,請參見 資料流程圖概覽。

備註

非基於時長的視窗設計則需要 azureiotoperations/graph-dataflow-window:1.1.0 或更晚。

轉換使用表達式語言來計算數值、測試條件及參考欄位。 表達式以位置指代輸入,而非名稱:列表中的 inputs 第一個輸入為 $1,第二個為 $2,依此類推。 像 cToF 這樣的內建函式會轉換及操作這些值。

完整的運算子、函式、資料型態及元資料欄位清單,請參見 Expressions 參考文獻。

視窗轉換會加入如 average、 min、 max等僅在累積規則中可用的聚合函數。 完整列表請參見 聚合函數。

先決條件

  • Azure IoT 操作 的一個實例部署在 Kubernetes 叢集中。 如需詳細資訊,請參閱 部署 Azure IoT 作業。
  • 在部署過程中,會自動建立一個指向 default 的預設登錄端點,名為 mcr.microsoft.com。

本文Azure CLI範例使用環境變數,讓你可以設定一次每個值,然後複製貼上指令 as-is。 如果您使用的是在 快速入門 中的 Azure IoT 操作 Codespaces 環境,系統已為您設定好這些變數,因此您可以略過此步驟。 否則,在執行指令前,先在 shell 裡設定以下環境變數。

以下腳本設定最常用的環境變數:

環境變數 說明
SUBSCRIPTION_ID 包含您的 Azure IoT 操作 實例的訂閱 ID。
RESOURCE_GROUP 包含你的 Azure IoT 操作 實例的資源群組名稱。
AIO_INSTANCE_NAME 你的 Azure IoT 操作 實例名稱。 要列出你的實例,請執行 az iot ops list -o table。
CLUSTER_NAME 這是支援 Azure Arc 的 Kubernetes 叢集名稱,該叢集負責承載你的實例。
LOCATION 用於新資源的 Azure 區域,例如 eastus。
SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

你只需要設定這篇文章所使用的變數。 本文可能會使用額外環境變數來表示你選擇的資源名稱。 該文章會說明如何在引入之處進行設定。

有狀態圖的縮放限制

這很重要

視窗與節流轉換是 有狀態的。 每個實例都維持自己的狀態,實例之間不會共享這個狀態。 當資料流剖面 實例數 大於一時, 共享訂閱 會在實例間分配訊息,因此每個實例只看到訊息的子集。 視窗 轉換會計算部分資料集上的平均值、求和值和計數等彙總值,而 節流 轉換則在每個實例中獨立強制執行設定的速率限制,而不是在整個管線中統一套用。

將任何使用視窗或節流轉換的資料流圖,其資料流設定檔執行個體計數設為 1。 僅使用映射、篩選、分支及串接轉換的無狀態資料流圖,可以安全地使用更高的實例數量來提升吞吐量。

何時使用視窗轉換

當你接收到高頻感測器資料,想在傳送前降低音量時,使用視窗轉換。 常見情況包括:

  • 計算平均值:溫度感測器每秒發布一次,但你的雲端應用程式只需 30 秒的平均值。
  • 追蹤極限:你要在每一分鐘的間隔內取得最小和最高壓力讀數。
  • 計算事件:你需要知道過去五分鐘內發生了多少門開啟事件。
  • 建立生產批次:你要為每個固定大小的批次計算統計數據,例如每100個包裹從填料線出來一次。
  • 對狀態變化做出反應:你想知道操作訊號何時改變,例如混頻器何時從 running 切換到 draining。

視窗轉換的運作方式

視窗變換有兩個內部步驟,依序相連:

  1. 視窗:暫存訊息,直到其中一個已設定的關閉條件觸發時為止。
  2. 累積:當視窗關閉時套用你的聚合規則。 轉換將視窗中的所有訊息簡化為單一輸出訊息。

備註

視窗轉換必須配置至少一個閉合條件:delay、、countmemory或triggers。

設定視窗關閉條件

從版本 1.1.0開始,視窗轉換會在現有 delay 的設定鍵外新增三個配置鍵:

組態金鑰 視窗類型 Purpose
delay 以持續時間為基礎的視窗 在固定時間後關閉視窗。
count 基於計數的視窗 在發送固定數量的訊息後關閉視窗。
memory 記憶體型視窗 當緩衝的有效載荷大小達到上限時,關閉視窗。
triggers 觸發式視窗 當自訂表達式值為 true時關閉視窗。

以持續時間為基礎的視窗

使用 delay 設定在固定時間後關閉視窗。 此設定控制每個翻滾視窗持續多久。

備註

延遲步驟會將訊息時間戳對齊到窗口邊界。 如果訊息在 10 秒視窗開始後的第 7 秒抵達,則歸入 10 秒邊界。

備註

如果你沒有提供 delay,視窗會以 60 秒的預設超時作為安全機制。

在視窗轉換設定中,將 視窗持續時間 設為秒數。 例如,若是 30 秒的輪轉視窗,請將它設為 30。

房產 類型 說明
type 字串 必須是 "duration"。
delaySeconds uint64 距離窗口關閉的秒數。 必須大於 0。

基於計數的視窗

使用 count 設定在發送固定訊息數量後關閉視窗。

在視窗轉換設定中,將 訊息計數 設為 , 5 邊界訊息行為設為 messageInCurrent。

房產 類型 說明
type 字串 必須是 "messageCount"。
maxMessageCount uint64 在視窗關閉前需要緩衝的訊息數量。 必須大於 0。
boundaryMessage 字串 關閉視窗的訊息是留在當前視窗(messageInCurrent)或啟動下一個視窗(messageInNext)。

記憶體型視窗

當緩衝有效載荷大小達到上限時,使用該 memory 配置關閉視窗。

在視窗轉換設定中,將 緩衝區大小 設為 1048576 位元組,並將邊界訊息行為設為 messageInNext。

房產 類型 說明
type 字串 必須是 "bufferSize"。
maxBufferBytes uint64 視窗關閉前的最大累積有效載荷位元組數。 必須大於 0。
boundaryMessage 字串 關閉視窗的訊息是留在當前視窗(messageInCurrent)或啟動下一個視窗(messageInNext)。

觸發式視窗

當視窗應根據訊息內容或目前視窗內的執行狀態關閉時,請使用 triggers 設定。

在視窗轉換設定中,加入一個觸發規則,包含輸入欄位 temperature、表達式 running_sum($1) + $1 > 100,以及邊界訊息行為 messageInCurrent。

房產 Required 說明
type 是的 必須是 "expression"。
rules 是的 觸發規則的陣列。 系統會依序針對每則訊息評估規則;第一個符合的規則會關閉視窗。
datasets No 會參照狀態存放區的選用狀態存放區資料集

每個觸發規則都支援以下欄位:

房產 Required 說明
inputs 是的 輸入欄位參考陣列。 表達式會綁定於 $1、 $2、 ,依此類推。
trigger 是的 當此布林運算式的運算結果為 true 時,會關閉視窗。
boundaryMessage 是的 關閉視窗的訊息是留在當前視窗(messageInCurrent)或啟動下一個視窗(messageInNext)。

該 inputs 欄位支援資料流程圖中其他地方使用的相同輸入語法,包括純欄位、 ?? 預設值、 ? $last、 $context(key).field和 $metadata.*。 如需更多關於如何使用 $context(key) 的詳細資訊,請參閱 使用外部資料擴充。

觸發表示式可以使用一般圖形表示式函數,以及下列會在視窗關閉時重設的執行狀態函數:

功能 說明
running_sum($1) 目前視窗中先前訊息裡 $1 的累計總和
running_avg($1) 先前訊息中 $1 的累積平均值。
running_min($1) 先前訊息中出現的 $1 最小值。 在第一個訊息時回傳 $1 (其中一個元素的最小值就是它本身)。
running_max($1) 先前訊息中出現的 $1 最大值。 在第一則訊息時回傳 $1 (其中一個元素的最大值是它本身)。
running_count($1) 出現 $1 的訊息數量。
running_count() 總訊息數量(無欄位篩選)。
first($1) 目前視窗中 $1 的第一個非空值。 在第一則訊息中傳回 $1。
changed($1) true 如果 $1 與前一訊息中的值不同。 false 在視窗的第一則訊息中(沒有可供比較的先前值)。
prev($1) 目前視窗中先前訊息裡 $1 的最近一個非空值 當 $1 訊息為空時會被跳過(儲存值不會被覆寫)。 在視窗的第一則訊息時回傳 $1 。

備註

running_sum($1) 類似函式則回傳先前處理過的訊息數值。 對於目前的訊息,請使用 $1。

觸發規則範例

請使用以下範例來檢視完整觸發配置物件中的共通 inputs 與 trigger 模式:

  • 這個範例顯示一個一般的觸發運算式。 當電流 temperature 超過80時,視窗會關閉。
{
  "type": "expression",
  "rules": [
    {
      "inputs": ["temperature"],
      "trigger": "$1 > 80",
      "boundaryMessage": "messageInCurrent"
    }
  ]
}
  • 此範例展示了一個觸發表達式,該 running_sum($1) + $1 表達式將當前視窗中的先前訊息與當前訊息合併,當閾值超過時關閉視窗。
{
  "type": "expression",
  "rules": [
    {
      "inputs": ["temperature"],
      "trigger": "running_sum($1) + $1 > 100",
      "boundaryMessage": "messageInCurrent"
    }
  ]
}
  • 此範例展示了空安全輸入處理,加上temperature ?? 0messageInNext將邊界訊息置於下一個視窗。
{
  "type": "expression",
  "rules": [
    {
      "inputs": ["temperature ?? 0"],
      "trigger": "running_avg($1) > 80",
      "boundaryMessage": "messageInNext"
    }
  ]
}
  • 此範例顯示一個以中繼資料為基礎的觸發條件,其中當來自 $metadata.topic 的主題值為特定值時,視窗會關閉。
{
  "type": "expression",
  "rules": [
    {
      "inputs": ["$metadata.topic"],
      "trigger": "$1 == \"telemetry/high-priority\"",
      "boundaryMessage": "messageInCurrent"
    }
  ]
}
  • 此範例展示如何使用資料集擴充的觸發規則:它會將訊息 factoryId 對應到狀態儲存區中的資料列,從 shiftId 讀取 $context(factory).shiftId,並在該 shift 值變更時關閉視窗(changed($1))。
{
  "type": "expression",
  "datasets": [
    {
      "key": "factory",
      "inputs": ["$source.factoryId", "$context.factoryId"],
      "expression": "$1 == $2"
    }
  ],
  "rules": [
    {
      "inputs": ["$context(factory).shiftId"],
      "trigger": "changed($1)",
      "boundaryMessage": "messageInCurrent"
    }
  ]
}

在此範例中,由 表示 factory 的狀態儲存資料集預期包含像 factoryId 和 shiftId這樣的欄位。

邊界行為

boundaryMessage 設定可控制,當訊息造成以筆數、記憶體或觸發為基礎的視窗關閉時,該訊息會發生什麼情況:

  • messageInCurrent:在關閉視窗中包含邊界訊息。
  • messageInNext: 先關閉目前的視窗,然後再開啟下一個帶有邊界訊息的視窗。

如果 messageInNext 在新視窗的第一則訊息上觸發,系統會隱藏該次關閉動作,避免發出空白視窗。

備註

以持續時間為基礎的視窗不使用 boundaryMessage。 時長邊界是基於時間的,而非訊息的,因此沒有邊界訊息需要放在當前或下一個視窗。

結合關閉條件

你可以在同一張圖中結合持續時間、計數、記憶和觸發條件。

  • 持續時間由計時器決定並評估。
  • 對於每個進來訊息,訊息驅動條件依序評估如下: Memory > Count > Trigger。
  • 在 triggers.rules內,規則依序評估,且第一個匹配的規則獲勝。

在訊息驅動條件下,當訊息同時滿足多個條件時,評估順序對累積結果很重要。 例如,若 memory 使用 messageInCurrent 且 count 使用 messageInNext,則符合兩個條件的訊息即遵循記憶體配置。 訊息會留在當前視窗,並貢獻該視窗的累積輸出。

定義累積規則

每個累積規則都指定如何將訊息視窗壓縮成單一輸出值。 配置鍵為 rules。

在視窗轉換配置中,加入一個包含輸入 temperature、輸出 avgTemperature及聚合函數 average($1)的累積規則。

房產 Required 說明
inputs 是的 每則進來訊息中應讀取的欄位路徑清單。
output 是的 彙總結果的欄位路徑。 每條規則必須有唯一的輸出。
expression 是的 公式將視窗的輸入值簡化為單一標量。 必須包含至少一個聚合函數。
description No 人類易讀的描述。

與地圖規則不同, expression 是每個累積規則 的必備 條件。 單獨使用 $1 不適用,因為它參考的是一組數值,而非單一標量。 你必須用像 average($1). 這樣的聚合函數包裹它。

範例:用十則訊息批次減少雜訊

如需完整的單資產圖、合成輸入和輸出,以及部分批次指引,請參見 降噪。

彙總函數

功能 退貨 空白視窗行為
average 數值的平均值 錯誤
sum 數值總和 0.0
min 最小數值 錯誤
max 最大數值 錯誤
count 具有該欄位的訊息數量 0
first 視窗中的第一個數值 錯誤
last 視窗中的最後一個數值 錯誤

每個函數以單一位置變數作為參數($1 第一個輸入 、第二個輸入 $2 ,依此類推)。

非數值:、 averagesum、 min和 max 函式會靜默跳過非數值值。

以存在與否為基礎的函式:count、first 和 last,無論值的型別為何,都會依欄位是否存在來運作。

合併聚合

在單一運算式中結合多個彙總函數:

加入一條包含輸入 temperature 和 humidity的規則,以及表達式 average($1) + max($2)。

要轉換匯總值,請將轉換函數套用在聚合之外。 例如,將 cToF(average($1)) 平均溫度轉換為華氏度。

每個聚合函數必須直接參考一個位置變數。 average($1) + max($2) 是有效的,但 average($1 + $2) 又不是。

與地圖規則的差異

能力 地圖規則 累加規則
需要運算式 No 是的
萬用字元輸入 Supported 不支援
$metadata 存取 Supported 不支援
$context 豐富化 Supported 不支援
? $last 指令 Supported 不支援
輸出內容類型 匹配輸入 一律為 application/json

完整配置範例

此範例顯示完整的視窗設定,會在經過 30 秒、累積 5 則訊息、緩衝達 1,048,576 個位元組,或當 running_sum($1) + $1 > 100 時關閉視窗。 此範例會針對後 3 個條件將 boundaryMessage 值設為 messageInCurrent,且視窗會在關閉時計算溫度統計資料。

關閉視窗的條件取決於訊息的時序、數量、有效載荷大小及內容。 以下範例展示了每個閉合條件的結果輸出。

期限結束

如果沒有其他條件優先觸發,且視窗在收到下列三則訊息後達到 30 秒:

{ "temperature": 21.5 }
{ "temperature": 23.0 }
{ "temperature": 19.8 }

輸出訊息為:

{
  "avgTemperature": 21.433333333333334,
  "minTemperature": 19.8,
  "maxTemperature": 23.0,
  "readingCount": 3,
  "tempRange": 3.2
}

計數結束

如果視窗在其他任何條件觸發前,收到下列五則訊息:

{ "temperature": 20.0 }
{ "temperature": 22.0 }
{ "temperature": 21.0 }
{ "temperature": 24.0 }
{ "temperature": 23.0 }

輸出訊息為:

{
  "avgTemperature": 22.0,
  "minTemperature": 20.0,
  "maxTemperature": 24.0,
  "readingCount": 5,
  "tempRange": 4.0
}

記憶體關閉

如果緩衝的承載大小在其他任何條件觸發前達到 1,048,576 位元組,例如收到下列這兩則大型訊息之後:

{ "temperature": 21.0, "payloadPad": "<large string>" }
{ "temperature": 22.5, "payloadPad": "<large string>" }

輸出訊息為:

{
  "avgTemperature": 21.75,
  "minTemperature": 21.0,
  "maxTemperature": 22.5,
  "readingCount": 2,
  "tempRange": 1.5
}

觸發器閉合

如果觸發運算式 running_sum($1) + $1 > 100 在其他任何條件之前觸發,例如收到下列這三則訊息之後:

{ "temperature": 40.0 }
{ "temperature": 35.0 }
{ "temperature": 30.0 }

輸出訊息為:

{
  "avgTemperature": 35.0,
  "minTemperature": 30.0,
  "maxTemperature": 40.0,
  "readingCount": 3,
  "tempRange": 10.0
}

在 Operations 經驗中,建立一個帶有視窗轉換的資料流程圖:

  1. 新增一個會從 讀取的telemetry/temperature。
  2. 新增 視窗轉換功能。 設定 30 秒的持續時間視窗、5 則訊息的計數限制、1,048,576 位元組的緩衝區大小限制,以及在 temperature 上使用運算式 running_sum($1) + $1 > 100 的觸發規則。 對於計數、記憶體和觸發條件,將邊界訊息行為設為 messageInCurrent。 新增場上平均、最小、最大、計數和距離 temperature 的累積規則。
  3. 新增一個目的地 並發送到telemetry/aggregated。

下一步