為資料流建置 WASM 模組

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,請參閱:

先決條件

開發環境:

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:

  1. 針對資料夾,請選取您要建立專案的位置。 你可以為這個專案建立一個新的資料夾。
  2. 輸入 my-graph 作為名稱。
  3. 選擇 Python 作為語言。
  4. 選擇 「地圖 」作為類型。
  5. 輸入 map 作為名稱。

你現在擁有一個新的 VS Code 工作區,裡面有基本的專案結構和起始檔案。 起始檔案包含 graph.dataflow.yaml 檔案和地圖運算子範本的原始碼。

這很重要

若要在已部署的 Azure IoT 操作 實例中使用 Python 模組,您必須部署該實例時,代理記憶體設定檔設為 Medium 或 High。 如果你把記憶體設定檔設為 Low 或 Tiny,實例就無法拉取 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 操作:建立運算子以建立新的運算子:

  1. 選擇 Rust 作為語言。
  2. 選擇 篩選 器作為操作員類型。
  3. 輸入 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:

  1. 請選擇圖表檔案。graph.dataflow.yaml
  2. 選擇 釋放 作為跑步模式。
  3. 請選擇你複製到工作區的 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。