部署 WebAssembly(WASM)模組與圖定義

Azure IoT 操作 的資料流程圖支援 WebAssembly(WASM)模組,用於邊緣的自訂資料處理。 您可以將自訂商務規則和資料轉換部署為資料流程管線的一部分。

這很重要

資料流程圖目前僅支援 MQTT、Kafka 和 OpenTelemetry 端點。 其他端點類型如 資料湖、Microsoft Fabric OneLake、Azure Data Explorer 及本地儲存則不被支援。

這很重要

目前唯一支援圖形定義以進行自訂處理的連接器是 HTTP/REST 連接器。

這很重要

目前,作業體驗 Web UI 僅支援建立及檢視以 Azure Container Registry(ACR)為來源的資料流圖成品;對於內建轉換,亦支援以 mcr.microsoft.com 為來源的資料流圖成品。 欲了解更多,請參閱營運經驗網頁介面,僅顯示來自Azure Container Registry(ACR)及 mcr.microsoft.com 的資料流圖產物。

先決條件

  • Azure IoT 操作 的一個實例部署在 Kubernetes 叢集中。 更多資訊請參見 部署 Azure IoT 操作。
  • 指向您要從中提取模組和圖形的容器登錄的登錄端點。 欲了解更多資訊,請參閱 「配置登錄端點」。 如果要開始而不自行設定登錄檔,可以使用「ghcr.io」中描述的公開範例端點。

要將自己的模組和圖形推送到像 Azure Container Registry (ACR) 這樣的私有登錄檔,你還需要:

  • 存取像 ACR 這樣的容器登錄檔來儲存 WASM 模組和圖表。
  • 用於將 WASM 模組推送至登錄庫的 OCI Registry As Storage(ORAS)CLI。

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

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

環境變數 Description
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>

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

概觀

Azure IoT 操作 中的 WASM 模組、資料流程圖與連接器,讓你能在邊緣處理高效能且具安全性的資料。 WASM 運行於沙盒環境中,並支援 Rust 和 Python。

使用公開登錄檔的預建模組

你可以使用已發佈在公開 GitHub 容器登錄檔(ghcr.io)的azure-samples/explore-iot-operations預建 WASM 範例模組與圖定義。

備註

ghcr.io需要在服務公開產物前進行認證的令牌交換,而目前的 Azure IoT 操作 執行環境並未執行匿名交換。 請為 public-ghcr 端點設定成品提取密碼,此密碼須以具備 read:packages 範圍的 GitHub 個人存取權杖 (PAT) 為基礎,而非使用匿名驗證。 關於端點與秘密步驟,請參見 使用公開登錄檔。

可用的樣本產物

建立 public-ghcr 登錄檔端點後,請在資料流程圖中使用 registryEndpointRef: public-ghcr 來參照它。 由於登錄端點主機為 ghcr.io,請在工件參考中包含儲存庫路徑 azure-samples/explore-iot-operations 。 以下範例模組與圖定義可供參考:

成品 Description
azure-samples/explore-iot-operations/graph-simple:1.0.0 簡單溫度轉換圖定義
azure-samples/explore-iot-operations/graph-complex:1.0.0 多感測器處理圖定義
azure-samples/explore-iot-operations/temperature:1.0.0 溫度轉換模組(華氏轉攝氏)
azure-samples/explore-iot-operations/window:1.0.0 基於時間的視窗模組
azure-samples/explore-iot-operations/snapshot:1.0.0 影像處理與物件偵測模組
azure-samples/explore-iot-operations/format:1.0.0 影像格式轉換模組
azure-samples/explore-iot-operations/humidity:1.0.0 濕度資料處理模組
azure-samples/explore-iot-operations/collection:1.0.0 多感測器資料聚合模組
azure-samples/explore-iot-operations/enrichment:1.0.0 元資料豐富模組
azure-samples/explore-iot-operations/filter:1.0.0 資料過濾模組

備註

公開的範例圖定義使用包含 azure-samples/explore-iot-operations 儲存庫路徑的模組參考,例如 azure-samples/explore-iot-operations/temperature:1.0.0。 此路徑是必要的,因為登錄端點主機為 ghcr.io。 如果你把產物複製到自己的登錄檔,請確保圖定義中的模組參考與你推送模組產物的路徑相符。

若要使用簡單的圖形與公開登錄檔,請參見 範例 1:基本部署,僅使用一個 WASM 模組 ,並作為 public-ghcr 登錄檔端點名稱。

使用私人登錄

如果你需要使用自訂模組或想自己架設範例模組的副本,可以設定一個私人容器登錄檔,例如 Azure Container Registry(ACR)。

設定容器登錄

Azure IoT 操作 需要一個容器登錄檔來拉取 WASM 模組和圖形定義。 你可以使用 Azure Container Registry(ACR)或其他相容於 OCI 的登錄檔。 要建立 ACR 實例,請參見部署 Azure Container Registry。 登錄檔存在後,建立指向該登錄的登錄端點——參見 建立登錄儀端點。

安裝 ORAS CLI

使用 ORAS CLI 將 WASM 模組和圖表定義推送至您的容器登錄。 如需安裝指示,請參閱安裝 ORAS。

從公用登錄提取範例模組

使用預先建置的範例模組:

# Pull sample modules and graphs
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/temperature:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/window:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/snapshot:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/format:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/humidity:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/collection:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/enrichment:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/filter:1.0.0

將模組推送至您的登錄

取得範例模組和圖形之後,請將它們推送至容器登錄。 將環境變數設定ACR_NAME為你的 Azure Container Registry 名稱。

這很重要

作業體驗會依據成品的 OCI config 媒體類型探索成品,而不是依據層媒體類型。 當你將工件推送到登錄檔時,必須設定正確的媒體類型,否則工件不會出現在操作體驗的介面中:

構件類型 所需的 OCI 配置媒體類型 所需層媒介類型
圖的定義 application/vnd.microsoft.aio.graph.v1+yaml application/yaml
WASM 模組 application/vnd.module.wasm.content.layer.v1+wasm application/wasm

如果你使用 CI/CD 管線或其他工具在登錄檔間複製產件,請確認它們是否保留這些媒體類型。 有些工具在傳輸過程中會移除或替換工件元資料,導致工件在操作體驗中默默消失。 欲了解更多資訊,請參閱 登錄檔紀錄要求。

選擇成品配置

你推送圖和模組時使用的工件名稱決定了圖定義中所需的模組參考。 關於登錄端點主機、工件路徑與模組參考的關聯背景,請參見 工件路徑與圖模組參考。

針對 Azure 範例圖形,當您將成品複製到自己的登錄時,請保留範例存放庫路徑。 圖定義會引用使用該路徑的模組:

<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0

在資料流程圖中使用 artifact: azure-samples/explore-iot-operations/graph-simple:1.0.0。 圖的定義使用 module: "azure-samples/explore-iot-operations/temperature:1.0.0"。

對於你自己的圖表,你可以選擇平面版面:

<YOUR_ACR_NAME>.azurecr.io/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/temperature:1.0.0

在資料流程圖中使用 artifact: graph-simple:1.0.0,並在圖表定義內使用 module: "temperature:1.0.0"。

或者選擇你自己的巢狀佈局:

<YOUR_ACR_NAME>.azurecr.io/factory/graphs/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/factory/graphs/temperature:1.0.0

在資料流程圖中使用 artifact: factory/graphs/graph-simple:1.0.0,並在圖表定義內使用 module: "factory/graphs/temperature:1.0.0"。

為了確保圖形和模組在操作體驗的網頁介面中可見,請如以下範例所示加入 --config 和 --artifact-type 標誌:

# Log in to your ACR
az acr login --name $ACR_NAME

# Push modules to your registry
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-simple.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-complex.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/window:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm window.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/snapshot:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm snapshot.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/format:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm format.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/humidity:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm humidity.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/collection:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm collection.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/enrichment:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm enrichment.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/filter:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm filter.wasm:application/wasm

小提示

您也可以推送自己的模組並建立自訂圖表,請參閱 設定自訂資料流程圖表。

更新運行中的圖中的模組

你可以在不停止圖形的情況下更新 WASM 模組。 當你想更新運算子的邏輯而不停止資料流時,這很有用。 例如,若要將溫度轉換模組從1.0.0更新為2.0.0,請在Azure範例工件配置中上傳新版本如下:

oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:2.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm

備註

如果你將新內容推送到 同一個標籤 (例如覆寫 azure-samples/explore-iot-operations/temperature:1.0.0),資料流程圖會自動接收更新後的模組,無需額外設定。 然而,如果你推送到一個新標籤(例如,azure-samples/explore-iot-operations/temperature:2.0.0),你必須同時更新圖形定義的 YAML 以引用新版本,並再次推送圖形元件。

開發自訂 WASM 模組

要為你的資料流程圖建立自訂的資料處理邏輯,可以用 Rust 或 Python 開發 WebAssembly 模組。 自訂模組可讓您實作內建運算子中無法使用的特殊化商務規則、資料轉換和分析。

如需完整的開發指引,包括:

  • 設定開發環境
  • 在 Rust 與 Python 中建立運算元
  • 了解資料模型和介面
  • 建置和測試模組

請參閱開發資料流程圖的 WebAssembly 模組。

如需建立和設定定義數據處理工作流程之 YAML 圖形定義的詳細資訊,請參閱 設定 WebAssembly 圖形定義。

登錄成品需求

操作體驗使用 OCI 產物元資料來發現並顯示圖表與模組。 當你建立自訂的 CI/CD 管線、在登錄檔間複製產物,或排除 UI 中缺失的產物時,了解這些需求非常重要。

文物發現的運作方式

當你使用 ORAS 將工件推送到註冊庫時,OCI 清單中包含兩個相關欄位:

  • Config 媒體類型:識別這是何種類型的成品。 運算經驗在此欄位上篩選以尋找圖形與模組。
  • 層媒體類型:描述實際檔案的內容格式(YAML 或 WASM)。

操作體驗使用設定媒體類型來進行發現,而非層媒體類型。 如果設定媒體類型缺失或錯誤,該雜訊存在於登錄檔,但不會出現在介面中。

必需媒體類型

構件類型 設定媒體類型(--config 或 --artifact-type) 層次媒體類型
圖的定義 application/vnd.microsoft.aio.graph.v1+yaml application/yaml
WASM 模組 application/vnd.module.wasm.content.layer.v1+wasm application/wasm

針對 Graph 定義,請使用--config標記來傳遞設定媒體類型。 將環境變數設REGISTRY為你的登錄主機(例如): <your-registry>.azurecr.io

oras push $REGISTRY/my-graph:1.0.0 \
  --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml \
  graph.yaml:application/yaml \
  --disable-path-validation

對於 WASM 模組,請用 --artifact-type 旗標傳遞:

oras push $REGISTRY/my-module:1.0.0 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  module.wasm:application/wasm

CI/CD 管線考量

如果你使用自動化管線在登錄檔間複製或升調產物(例如從暫存登錄檔到生產登錄檔),請確認管線是否保留 OCI 產物元資料。 有些工具在傳輸期間會移除或替換 config 媒體類型,導致成品在作業體驗中悄悄消失。

若要確認成品在傳輸後具有正確的中繼資料,請檢查其資訊清單:

oras manifest fetch $REGISTRY/my-graph:1.0.0 | jq '{mediaType, configMediaType: .config.mediaType}'

輸出結果應為:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "configMediaType": "application/vnd.microsoft.aio.graph.v1+yaml"
}

如果 configMediaType 顯示一般值,例如 application/vnd.oci.empty.v1+json,表示中繼資料已遭移除,而成品必須使用正確旗標重新推送。