搭配 WASM 模組使用結構描述登錄檔

結構登錄檔讓你能驗證訊息格式,並確保資料流程處理的一致性。 本文說明如何在 Azure IoT 操作 本地開發環境中,將結構登錄檔與 WASM 模組結合使用。

在完成本文步驟前,先建立本地開發環境,並在本地建置並執行圖形應用程式。 欲了解更多資訊,請參閱 建構 WASM 模組以了解資料流程。

先決條件

完成 Build WASM 資料流程模組中列出的先決條件。

開啟結構登錄範例工作區

如果你還沒克隆過 Explore IoT Operations 的儲存庫,請克隆。

開啟 samples/wasm/schema-registry-scenario 資料夾。 此資料夾包含以下資源:

  • graph.dataflow.yaml - 資料流程圖配置。
  • tk_schema_config.json - 主機應用程式在本地使用的 JSON 架構,用以驗證傳入訊息的有效負載,在其抵達下游操作員之前。 請保持此檔案與你發佈到 Microsoft Azure 環境的任何結構同步。
  • data/ - 取樣不同訊息格式的輸入資料以供測試。
  • operators/filter/ - 濾波器運算子的原始碼。
  • (可選)hostapp.env.list - VS Code 擴充功能在運行時自動生成一個,並添加TK_SCHEMA_CONFIG_PATH=tk_schema_config.json。 如果你提供自己的結構檔案,請確保變數指向該檔案。

了解模式設定

打開 tk_schema_config.json 檔案以查看結構定義:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "humidity": {
      "type": "integer"
    },
    "temperature": {
      "type": "number"
    }
  }
}

此架構定義了一個頂層 JSON 物件,可包含兩個數值屬性: humidity (整數)與 temperature (數字)。 如果需要同時要求,可以加 "required": ["humidity", "temperature"] 陣列,或隨著有效載荷格式演變而延長該 properties 區段。

以下限制適用於本地結構檔案(tk_schema_config.json)。 模式文件:

  • 使用標準 JSON Schema draft-07 語法,與 Azure IoT 操作 架構登錄檔所支援的草案相同。
  • 功能上就是你在雲端架構登錄檔註冊的內容。 你可以在兩者之間複製貼上,保持一致性。
  • 由主機應用程式透過環境變數 TK_SCHEMA_CONFIG_PATH來參考。

目前,本地開發執行時適用以下限制:

  • 只會載入一個結構設定檔。 不支援多檔案包含功能或目錄掃描。
  • $ref 不支援在本機指向外部檔案或 URL。 請保持結構描述為自我包含。 你可以使用內部的 JSON 指標參考,例如 {"$ref":"#/components/..."}。
  • 常用的 draft-07 關鍵字如 type、properties、required、enum、minimum、maximum、allOf、anyOf、oneOf、not 和 items 都有效。 底層驗證者可能會忽略較少見或進階的功能,如 contentEncoding 和 contentMediaType。
  • 請將結構大小控制在約 1 MB 以下,以加快冷啟動速度。
  • 版本控制和結構演化政策並非本地強制執行。 你有責任與雲端登錄檔保持一致。

如果你依賴在本地驗證失敗的進階結構,發布後再用同一架構與雲端登錄檔驗證以確保同位。

欲了解更多,請參閱 Azure IoT 操作 schema registry concepts。

檢視測試數據

該 data/ 資料夾包含三個測試檔案:

  • temperature_humidity_payload_1.json - 包含溫度與濕度資料。 然而,濕度值(175.1)並非結構中指定的整數,因此資料在結構驗證中失敗並被過濾掉。
  • temperature_humidity_payload_2.json - 僅包含濕度資料,並經過過濾。
  • temperature_humidity_payload_3.json - 包含溫度與濕度資料,並通過驗證。

建立並執行結構登錄檔情境

如果你之前已經停止本地執行環境,請按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Start Development Environment。 選擇 釋放 作為跑步模式。

  1. 按 Ctrl+Shift+P 開啟指令面板並搜尋 Azure IoT 操作: Build All Data Flow Operators。

  2. 選擇 釋放 作為建置模式。 等待建置完成。

  3. 再次按 Ctrl+Shift+P,搜尋 Azure IoT 操作: Run Application Graph。

  4. 請選擇圖表檔案。graph.dataflow.yaml

  5. 選擇 釋放 作為跑步模式。

  6. 在你的 VS Code 工作區選擇 data 輸入資料的資料夾。 DevX 容器會啟動,執行帶有樣本輸入的圖表。

驗證結構描述驗證

處理完成後:

  1. 請查看 data/output/ 資料夾中的結果。

  2. 輸出只包含已處理過的訊息版本 temperature_humidity_payload_3.json ,因為它符合結構規範。

  3. 該 data/output/logs/host-app.log 檔案包含日誌條目,指示根據結構驗證接受或拒絕哪些訊息。

此範例展示了結構登錄如何驗證收到的訊息,並過濾不符合定義結構的訊息。

在發佈模式下測試結束後,按 Ctrl+Shift+P 並搜尋 Azure IoT 操作: 停止開發環境,即可停止本地執行環境。