視窗轉換會將收到的訊息分組,並在視窗關閉時產生一個包含彙總值的單一輸出訊息。 你不必逐一轉發每一次讀數,而是可以計算統計數據,如平均值、最小值或計數,並將一個合併結果送往下游。
視窗會根據持續時間、計數、記憶體或觸發條件而關閉。 這些視窗為不重疊的輪轉視窗;不提供滑動視窗。
關於資料流程圖的概述以及在管線中轉換的組合方式,請參見 資料流程圖概覽。
備註
非基於時長的視窗設計則需要 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。
視窗轉換的運作方式
視窗變換有兩個內部步驟,依序相連:
- 視窗:暫存訊息,直到其中一個已設定的關閉條件觸發時為止。
- 累積:當視窗關閉時套用你的聚合規則。 轉換將視窗中的所有訊息簡化為單一輸出訊息。
備註
視窗轉換必須配置至少一個閉合條件: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 經驗中,建立一個帶有視窗轉換的資料流程圖:
- 新增一個會從 讀取的
telemetry/temperature。 - 新增 視窗轉換功能。 設定 30 秒的持續時間視窗、5 則訊息的計數限制、1,048,576 位元組的緩衝區大小限制,以及在
temperature上使用運算式running_sum($1) + $1 > 100的觸發規則。 對於計數、記憶體和觸發條件,將邊界訊息行為設為messageInCurrent。 新增場上平均、最小、最大、計數和距離temperature的累積規則。 - 新增一個目的地 並發送到
telemetry/aggregated。