Azure IoT 操作 中的自訂 WebAssembly(WASM)資料處理功能,能在您的 Azure IoT 操作 叢集內即時進行遙測資料處理。 透過部署自訂的 WASM 模組,你可以定義並執行資料轉換,作為資料流程圖、HTTP/REST 連接器或 MQTT 連接器的一部分。
本文說明如何使用 Azure IoT 操作 Data Flow VS Code 擴充功能、dataflow-dev CLI 或安裝於您環境中的標準工具,在部署至 Azure IoT 操作 叢集前,先在本地開發與測試 WASM 模組。 您將瞭解如何:
- 在本地執行圖形應用程式,執行包含範例資料的預建圖,以了解基本工作流程。
- 透過在 Python 和 Rust 中建立新的運算子,並具備映射與濾波功能,來建立自訂的 WASM 模組。
在積極建立運算子和圖表時,使用 VS Code 擴充功能作為內部開發循環,例如:撰寫程式碼、建置、審查錯誤、除錯、修改、更新圖表和發佈。
使用 dataflow-dev CLI 來處理以 CI/CD 為重點的圖品質工作流程,例如:建立現有程式碼、執行圖表、與已知良好結果的輸出測試,並隨時間監控品質。
在你想對建置與測試流程有更多掌控權,或需要與其他開發工具和工作流程整合的情況下,使用安裝在你環境中的標準工具。
本文說明如何在本地建置與測試你的 WASM 模組。 若要在 Azure IoT 操作 的資料流與連接器中使用它們,您必須將它們部署到您的 Azure IoT 操作 叢集,並在圖形或連接器配置中引用:
欲了解更多進階情境,請參閱 「使用狀態儲存建立有狀態 WASM 圖」、「 使用 WASM 模組的結構登錄」、「 除錯 WASM 模組」及「 測試 WASM 模組」。
擴充功能與 CLI 工具支援以下平台:
- Linux
- Windows 子系統 Linux 版(WSL)
- Windows(在 Windows 上執行擴充功能命令時,務必使用 Windows shell,例如 PowerShell 或命令提示字元)
欲了解更多關於 Azure IoT 操作 中的圖形與 WASM,請參閱:
先決條件
開發環境:
- Visual Studio 程式碼
- (可選)RedHat VS Code 的 YAML 擴充
- Azure IoT 操作 Data Flow 擴充套件 用於 VS Code。
- CodeLLDB 擴充功能 用於 VS Code 以支援除錯 WASM 模組
- Docker
Docker 映像檔:
docker pull mcr.microsoft.com/azureiotoperations/processor-app:1.1.8
docker tag mcr.microsoft.com/azureiotoperations/processor-app:1.1.8 host-app
docker pull mcr.microsoft.com/azureiotoperations/devx-runtime:0.1.10
docker tag mcr.microsoft.com/azureiotoperations/devx-runtime:0.1.10 devx
docker pull mcr.microsoft.com/azureiotoperations/statestore-cli:0.0.3
docker tag mcr.microsoft.com/azureiotoperations/statestore-cli:0.0.3 statestore-cli
docker pull eclipse-mosquitto
在本地執行圖形應用程式
本範例使用了一個範例工作空間,包含所有必要的資源,可在本地使用 VS Code 擴充套件建置與執行圖形應用程式。
在 VS Code 中開啟範例工作區
如果你還沒克隆過 Explore IoT Operations 的儲存庫,請克隆。
在 Visual Studio Code 中選取samples/wasm,並瀏覽至 > 資料夾,以開啟 資料夾。
建立運算元
按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Build All Operators。 選擇 釋放 作為建置模式。
此指令會在工作區建立所有運算子,並在資料夾中建立 .wasm 檔案 operators 。 你用這些 .wasm 檔案在本地執行圖形應用程式。
在本地執行圖形應用程式
要啟動本地執行環境,按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Start Development Environment。 選擇 釋放 作為跑步模式。
當本地執行環境正在執行時,按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Run Application Graph。 選擇 釋放 作為跑步模式。 此指令透過使用本地執行環境,將 graph.dataflow.yaml 檔案置於工作空間中,在本地執行圖形應用程式。
它也會從 hostapp.env.list 讀取設定,為資料流程運算子的組態參數設定環境變數 TK_CONFIGURATION_PARAMETERS。
當系統提示你輸入資料時,選擇工作區中的資料夾。data-and-images 此資料夾包含圖形應用的輸入資料檔案,包括溫度與濕度資料,以及快照模組的部分影像。
請等到您看到 VS Code 通知指出記錄已就緒:Log files for the run can be found at ...\wasm\data-and-images\output\logs。
輸出則位於資料夾output下方的data-and-images資料夾中。 你可以在工作區打開 output 資料夾查看輸出檔案。 包含檔名日期與時間的 .txt 檔案包含處理後的資料,範例如下:
{"tst":"2025-09-19T04:19:13.530381+0000","topic":"sensors","qos":0,"retain":0,"payloadlen":312,"properties":{"payload-format-indicator":1,"message-expiry-interval":10,"correlation-data":"...","user-properties":{"__ts":"001758255553528:00000:...","__protVer":"1.0","__srcId":"mqtt-source"},"content-type":"application/json"},"payload":{"temperature":[{"count":2,"max":653.888888888889,"min":204.44444444444449,"average":429.16666666666669,"last":204.44444444444449,"unit":"C","overtemp":true}],"humidity":[{"count":3,"max":85,"min":45,"average":69.666666666666671,"last":79}],"object":[{"result":"notebook, notebook computer; sliding door"}]}}
輸出顯示圖形應用程式處理了輸入資料並產生輸出。 輸出包含溫度與濕度資料,以及影像中偵測到的物體。
用自訂的 WASM 模組建立一個新的圖
這個情境會展示如何用自訂的 WASM 模組建立新的圖形應用程式。 圖形應用包含兩個運算子:一個 map 將溫度值從華氏轉換成攝氏度的運算子,另一個 filter 運算子則過濾低於500°C的訊息。
目前,在操作員名稱中不要使用連字號(-)或底線(_)。 VS Code 擴充功能強制執行這個要求,但如果你手動建立或重新命名模組,會造成問題。 對於模組如 filter、 map、 stateenrich或 schemafilter,請使用簡單的字母數字名稱。
你不是使用現有的範例工作區,而是從零開始建立一個新的工作區。 這個過程讓你學會如何建立新的圖形應用程式,並用 Python 和 Rust 編寫運算子。
用 Python 建立一個新的圖形應用程式專案
按 Ctrl+Shift+P 開啟 VS Code 指令面板,搜尋 Azure IoT 操作: Create Application:
- 針對資料夾,請選取您要建立專案的位置。 你可以為這個專案建立一個新的資料夾。
- 輸入
my-graph作為名稱。 - 選擇 Python 作為語言。
- 選擇 「地圖 」作為類型。
- 輸入
map作為名稱。
你現在擁有一個新的 VS Code 工作區,裡面有基本的專案結構和起始檔案。 起始檔案包含 graph.dataflow.yaml 檔案和地圖運算子範本的原始碼。
這很重要
若要在已部署的 Azure IoT 操作 實例中使用 Python 模組,您必須部署該實例時,代理記憶體設定檔設為
為地圖運算子模組新增 Python 程式碼
打開 operators/map/map.py 檔案,並用以下程式碼替換內容,將輸入溫度值從華氏轉換成攝氏度:
import json
from map_impl import exports
from map_impl import imports
from map_impl.imports import types
class Map(exports.Map):
def init(self, configuration) -> bool:
imports.logger.log(imports.logger.Level.INFO, "module4/map", "Init invoked")
return True
def process(self, message: types.DataModel) -> types.DataModel:
# TODO: implement custom logic for map operator
imports.logger.log(imports.logger.Level.INFO, "module4/map", "processing from python")
# Ensure the input is of the expected type
if not isinstance(message, types.DataModel_Message):
raise ValueError("Unexpected input type: Expected DataModel_Message")
# Extract and decode the payload
payload_variant = message.value.payload
if isinstance(payload_variant, types.BufferOrBytes_Buffer):
# It's a Buffer handle - read from host
imports.logger.log(imports.logger.Level.INFO, "module4/map", "Reading payload from Buffer")
payload = payload_variant.value.read()
elif isinstance(payload_variant, types.BufferOrBytes_Bytes):
# It's already bytes
imports.logger.log(imports.logger.Level.INFO, "module4/map", "Reading payload from Bytes")
payload = payload_variant.value
else:
raise ValueError("Unexpected payload type")
decoded = payload.decode("utf-8")
# Parse the JSON data
json_data = json.loads(decoded)
# Check and update the temperature value
if "temperature" in json_data and "value" in json_data["temperature"]:
temp_f = json_data["temperature"]["value"]
if isinstance(temp_f, int):
# Convert Fahrenheit to Celsius
temp_c = round((temp_f - 32) * 5.0 / 9.0)
# Update the JSON data
json_data["temperature"]["value"] = temp_c
json_data["temperature"]["unit"] = "C"
# Serialize the updated JSON back to bytes
updated_payload = json.dumps(json_data).encode("utf-8")
# Update the message payload
message.value.payload = types.BufferOrBytes_Bytes(value=updated_payload)
return message
確保 Docker 正在運行。 然後按 Ctrl+Shift+P 開啟指令面板,搜尋 Azure IoT 操作: Build All Operators。 建立 一個釋放 模組。
建置過程會將map.wasm檔案放入map資料夾中,該檔案屬於operators/map/bin/release操作符。
新增 Rust 程式碼以控制濾波器運算子模組
按下 Ctrl+Shift+P 開啟命令選擇區,並搜尋 Azure IoT 操作:建立運算子以建立新的運算子:
- 選擇 Rust 作為語言。
- 選擇 篩選 器作為操作員類型。
- 輸入
filter作為名稱。
打開 operators/filter/src/lib.rs 檔案,並用以下程式碼替換內容,以過濾溫度高於 500°C 的數值:
mod filter_operator {
use wasm_graph_sdk::macros::filter_operator;
use serde_json::Value;
fn filter_init(_configuration: ModuleConfiguration) -> bool {
// Add code here to process the module init properties and module schemas from the configuration
true
}
#[filter_operator(init = "filter_init")]
fn filter(input: DataModel) -> Result<bool, Error> {
// Extract payload from input to process
let payload = match input {
DataModel::Message(Message {
payload: BufferOrBytes::Buffer(buffer),
..
}) => buffer.read(),
DataModel::Message(Message {
payload: BufferOrBytes::Bytes(bytes),
..
}) => bytes,
_ => return Err(Error { message: "Unexpected input type".to_string() }),
};
// ... perform filtering logic here and return boolean
if let Ok(payload_str) = std::str::from_utf8(&payload) {
if let Ok(json) = serde_json::from_str::<Value>(payload_str) {
if let Some(temp_c) = json["temperature"]["value"].as_i64() {
// Return true if temperature is above 500°C
return Ok(temp_c > 500);
}
}
}
Ok(false)
}
}
打開檔案 operators/filter/Cargo.toml 並新增以下相依關係:
[dependencies]
# ...
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
確保 Docker 正在運行。 然後按 Ctrl+Shift+P 開啟指令面板,搜尋 Azure IoT 操作: Build All Operators。 建立 一個釋放 模組。
建置過程會將filter.wasm檔案放入filter資料夾中,該檔案屬於operators/filter/bin/release操作符。
在本地執行圖形應用程式並使用範例資料
請開啟 graph.dataflow.yaml 檔案,並以下列代碼取代內容:
metadata:
$schema: "https://www.schemastore.org/aio-wasm-graph-config-1.0.0.json"
name: "Temperature Monitoring"
description: "A graph that converts temperature from Fahrenheit to Celsius, if temperature is above 500°C, then sends the processed data to the sink."
version: "1.0.0"
vendor: "Microsoft"
moduleRequirements:
apiVersion: "1.1.0"
runtimeVersion: "1.1.0"
operations:
- operationType: source
name: source
- operationType: map
name: map
module: map
- operationType: filter
name: filter
module: filter
- operationType: sink
name: sink
connections:
- from:
name: source
to:
name: map
- from:
name: map
to:
name: filter
- from:
name: filter
to:
name: sink
將 data 包含樣本資料的資料夾從複製樣本庫 explore-iot-operations\samples\wasm\data 複製到目前的工作區。 該 data 資料夾包含三個包含範例輸入溫度資料的 JSON 檔案。
如果你之前已經停止本地執行環境,請按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Start Development Environment。 選擇 釋放 作為跑步模式。
按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Run Application Graph:
- 請選擇圖表檔案。
graph.dataflow.yaml - 選擇 釋放 作為跑步模式。
- 請選擇你複製到工作區的
data資料夾。
DevX 容器會啟動來執行圖表。 處理後的結果會儲存在資料夾中 data/output 。 資料夾中的 output 文字檔包含已處理的資料,溫度轉換為攝氏並依閾值過濾。
想了解如何將自訂的 WASM 模組和圖表部署到你的 Azure IoT 操作 實例,請參見 部署 WASM 模組與資料流程圖。
當你建置好 WASM 模組並設定好圖形應用程式後,可以將它們部署到 Azure IoT 操作 叢集,並在圖形或連接器設定中參考:
Troubleshoot
建置錯誤
| 錯誤 | 原因 | 修正 |
|---|---|---|
error[E0463]: can't find crate for std |
遺失 WASM 目標 |
rustup target add wasm32-wasip2執行 |
error: no matching package found 的 wasm_graph_sdk |
失蹤貨物登記 | 將[registries]區塊加入.cargo/config.toml,如同「本地執行圖形應用程式」所示 |
componentize-py 找不到 WIT 檔案 |
架構路徑錯誤 | 使用 -d 旗標,並提供架構目錄的完整路徑。 所有 .wit 檔案必須同時存在,因為它們彼此參照。 |
componentize-py 版本不匹配 |
使用不同版本產生的繫結 | 刪除產生的綁定目錄,然後用相同 componentize-py 版本重新生成 |
wasm-tools 元件檢查失敗 |
目標錯誤或元件轉接器缺失 | 確保你使用的是 wasm32-wasip2,而不是 wasm32-wasi 或 wasm32-unknown-unknown。 |
執行階段錯誤
| 癥狀 | 原因 | 修正 |
|---|---|---|
| 運算元因 WASM 回溯而當機 | 缺少或無效的設定參數 | 在 init 中新增防禦性解析及預設值。 請參閱 模組配置參數。 |
init 回傳 false,資料流無法啟動 |
設定驗證失敗 | 請檢查資料流日誌是否有錯誤訊息。 確認 moduleConfigurations 名字與你的程式碼相符。 |
| 模組會載入但沒有輸出 |
process 傳回錯誤或丟棄所有資料的篩選條件 |
新增登入 process 以追蹤資料流。 |
Unexpected input type |
模組收到錯誤 data-model 版本 |
在開始 process 時加個類型檢查,處理意外變體。 |
| 模組單獨運作,但在複雜圖形中會崩潰 | 跨節點重複使用時缺少設定 | 每個圖節點都需要自己的 moduleConfigurations 條目。 |
常見陷阱
- 忘記 ORAS 推送上的
--artifact-type。 沒有它,操作體驗介面無法正確顯示你的模組。 -
name中的moduleConfigurations不匹配。 名稱必須是<module>/<operator>(例如),module-temperature/filter且與圖定義的operations部分相符。 - 使用
wasm32-wasi而非wasm32-wasip2。 Azure IoT 操作需要 WASI 預覽版 2 目標。 - Python:在不複製 schema 目錄的情況下,在 sample repo 外工作。 所有
.wit檔案必須共置,因為它們彼此互相參考。
已知問題
YAML 中的布林值:為避免驗證錯誤,布林值必須以字串形式引用。 例如,使用
"True"和"False"代替true和false。使用未加引號的布林值時的錯誤範例:
* spec.connections[2].from.arm: Invalid value: "boolean": spec.connections[2].from.arm in body must be of type string: "boolean" * spec.connections[2].from.arm: Unsupported value: false: supported values: "False", "True"Python模組需求 :若要使用 Python 模組,Azure IoT 操作 必須在部署時,配置 MQTT 中介來使用Medium 或High 記憶體設定檔。 Python 模組無法在記憶體配置設為Low或Tiny時被載入。模組部署時機:拉取並套用 WASM 模組可能需要一些時間,通常約一分鐘,視網路狀況與模組大小而定。
建置錯誤細節:當建置失敗時,彈出通知中的錯誤訊息可能無法提供足夠細節。 請查看端子輸出以獲得更具體的錯誤資訊。
Windows 相容性:在 Windows 首次執行圖形應用程式時,可能會遇到錯誤訊息「指令失敗,且有退出代碼 1」。如果發生此錯誤,請重試操作,應該會正常運作。
主機應用程式穩定性:本地執行環境有時會停止運作,需要重新啟動才能恢復。
遠端除錯限制:目前,由於 LLDB 版本不相容,無法遠端除錯 Azure Linux 3.0 中運行的 WASM 模組。
復原程序
VS Code 擴充功能重置:如果 VS Code 擴充功能出現異常行為,請嘗試卸載並重新安裝,然後重新啟動 VS Code。