結構登錄檔讓你能驗證訊息格式,並確保資料流程處理的一致性。 本文說明如何在 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。 選擇 釋放 作為跑步模式。
按
Ctrl+Shift+P開啟指令面板並搜尋 Azure IoT 操作: Build All Data Flow Operators。選擇 釋放 作為建置模式。 等待建置完成。
再次按
Ctrl+Shift+P,搜尋 Azure IoT 操作: Run Application Graph。請選擇圖表檔案。
graph.dataflow.yaml選擇 釋放 作為跑步模式。
在你的 VS Code 工作區選擇
data輸入資料的資料夾。 DevX 容器會啟動,執行帶有樣本輸入的圖表。
驗證結構描述驗證
處理完成後:
請查看
data/output/資料夾中的結果。輸出只包含已處理過的訊息版本
temperature_humidity_payload_3.json,因為它符合結構規範。該
data/output/logs/host-app.log檔案包含日誌條目,指示根據結構驗證接受或拒絕哪些訊息。
此範例展示了結構登錄如何驗證收到的訊息,並過濾不符合定義結構的訊息。
在發佈模式下測試結束後,按 Ctrl+Shift+P 並搜尋 Azure IoT 操作: 停止開發環境,即可停止本地執行環境。