Lakeflow Designer 讓你能創建 自訂操作員,這些操作員會直接出現在畫布中,與內建操作符並列。 利用它們來擴充 Lakeflow Designer,加入你自己的商業邏輯、計算或整合。 自訂運算子過去稱為使用者定義運算子(UDOs)。
客製化運算子分為兩種作用域:
- 本機:操作員屬於一個視覺資料準備檔案。 描述轉換,Genie Code 會產生運算元件。 參見 「使用 Genie Code 建立本機自訂運算子」。
- 共用:操作員已註冊在工作區,因此你和其他使用者可以將其加入任何視覺化資料前處理檔案。 其邏輯是 Python 函式或 Unity Catalog 函式,並以 YAML 描述。 你可以自己寫,或請 Genie Code 幫忙製作。 請參閱 自訂運算子的運作方式。
Note
當你新增一個需要 Python 套件或系統函式庫,而筆記本環境中沒有這些套件或程式庫的自訂操作符時,Designer 會提示你新增這些套件或程式庫。 選擇新增相依,然後在環境側窗格中選擇套用來安裝它們。 參見 選擇無伺服器環境。
用 Genie Code 建立本地自訂操作器
當您的工作區中有 Genie Code 時,您可以從 Lakeflow Designer 畫布建立本地自訂運算子:
在 操作員 面板中,選擇 建立自訂操作員。
輸入描述,並可選擇輸入名稱。 選擇 產生預覽。
Tip
例如,請輸入以下描述:
Count the business days between two date columns, excluding weekends. Let me choose the start and end date columns and name the output column.檢視產生的設定和 Python 函式,然後選擇批准並建立。
Designer 將本地運算子的定義儲存在目前檔案中,並將本地運算子加入 Operators 面板。 使用操作員的動作選單來編輯或刪除定義。 你必須先從畫布中移除所有運算元實例,才能刪除其定義。
發佈本地自訂 Operator
若要在其他視覺資料準備中重複使用本機自訂運算子,請發佈:在 運算子 面板中,開啟該運算子的動作選單,然後選取 發佈。 發佈會建立一個共享的自訂運算子,更新目前檔案中的每個實例以使用該運算子,並移除本地定義。 在對話框中,選擇運算子檔案的位置,並選擇是否將運算子加入你的 使用者 或 工作區 登錄。
選擇共用的運算子類型
共享自訂運算子有三種類型:
-
python-run-function:儲存在工作區中的獨立 YAML 檔案,內含內嵌 Python 程式碼。 最適合用於 DataFrame 層級轉換與外部整合。 權限是在工作區檔案層級管理的。 -
uc-udf:封裝 Unity Catalog 的純量函式。 最適合用於欄位層級轉換。 存取權限受 Unity 目錄權限所規範。 -
uc-udtf:封裝了 Unity Catalog 的表值函式。 最適合用於資料表層級的轉換,例如機器學習的聚類和聚合。 存取權限受 Unity 目錄權限所規範。
| Feature | python-run-function |
uc-udf |
uc-udtf |
|---|---|---|---|
| 使用案例範例 | DataFrame 轉換、API 整合、電子郵件通知 | 欄位層級計算(BMI、利率) | 機器學習叢集、跨列聚合 |
| 輸入 | 資料框架 | 單一價值 | 整個表格,逐列顯示 |
| Output | 資料框架 | 單一值 | 表格(多列) |
| 需要 Unity 目錄功能 | No | Yes | Yes |
| 存取控管 | Workspace 檔案權限 | Unity Catalog 權限 (EXECUTE, USE SCHEMA) |
Unity Catalog 權限 (EXECUTE, USE SCHEMA) |
| 支援的語言 | 只使用 Python | SQL 或 Python 在 SQL 包裝器中 | SQL 或 Python 在 SQL 包裝器中 |
自訂操作員的運作方式
共用的自訂運算子包含:
-
運算子邏輯:當運算子執行時執行的程式碼。 這是適用於
run()運算子的內聯 Pythonpython-run-function函式,或是適用於uc-udf和uc-udtf運算子的 Unity Catalog 函式。 請參閱 Lakeflow Designer 自訂運算子的撰寫邏輯。 -
YAML 設定:告訴 Lakeflow Designer 如何在 UI 中呈現運算元,包括運算元名稱、描述、輸入參數、UI 元件及埠口。 所有操作員類型都使用該
custom-operator-v0.1.0架構。 對於運算子而言python-run-function,YAML 是一個獨立的工作區檔案,同時儲存內嵌程式碼。 對於 Unity Catalog 函式,YAML 會嵌入在函式主體中。 請參見 自訂運算元 YAML 參考資料。 -
註冊檔案:
.custom_operators.yaml中的一個條目,可讓 Lakeflow Designer 識別該運算子。 請參閱 註冊並部署您的運算子至 Lakeflow Designer。
建立共用運算子
要從頭到尾建立共用的自訂運算子:
- 選擇一種運算子類型。 請參閱 選擇共享運算子類型。
- 寫出並測試操作器邏輯。 請參閱 Lakeflow Designer 自訂運算子的撰寫邏輯。
- 請用 YAML 描述操作符:名稱、設定屬性、UI 元件及埠口。 請參見 自訂運算元 YAML 參考資料。
-
註冊該操作員:將其加入
.custom_operators.yaml。 請參閱 註冊並部署您的運算子至 Lakeflow Designer。 - 授予權限,讓其他使用者能發現並執行該運算子。 請參閱 權限。
- 使用運算子。 它會出現在 Lakeflow Designer 的 Operators 面板中,與內建的 operators 並列。
每個 教學 都會帶你逐步完成一個完整的操作。
Tip
要建立共享 python-run-function 運算子而不自己寫,請在側邊窗格中向 Genie Code 描述它。 Genie Code 會詢問是要為你註冊運算子,還是為整個工作區註冊運算子,然後寫入 YAML 檔案並註冊該運算子。 你仍然需要為其他使用者授予權限。 要更改共享操作員,請提供 Genie Code 其工作區 YAML 檔案路徑,並描述變更內容。
註冊並部署您的操作員至 Lakeflow Designer
為了讓你的操作員在 Lakeflow Designer 中出現,請將其註冊在 .custom_operators.yaml 一個檔案中:
- 工作空間層級: 將檔案放在工作區根目錄,讓操作員對所有使用者都可見。
-
使用者層級: 將檔案放入使用者主資料夾(
/Workspace/Users/<user-name>/.custom_operators.yaml),讓操作員只對你可見。
Note
Lakeflow Designer 仍然讀取名為 .user_defined_operators.yaml 的註冊檔案,所以現有的註冊設定仍可繼續運作。
在.custom_operators.yaml中註冊新操作員。 如果同一資料夾中已經有 .user_defined_operators.yaml 檔案,請將其條目移到 .custom_operators.yaml。 當兩個檔案同時存在於資料夾中時,Lakeflow Designer 只會讀取 .custom_operators.yaml。
此 operators: 區塊支援檔案路徑、Unity 目錄函式參考及 glob 圖案。 你可以混合使用不同的入門類型:
operators:
# File path (python-run-function operators)
- /Workspace/Users/me/operators/my_operator.yaml
# Glob pattern (registers all matching files)
- /Workspace/Users/me/operators/transforms/*.yaml
# UC function reference (uc-udf and uc-udtf operators)
- catalog: my_catalog
schema: my_schema
functionName: my_function
更新或移除操作員
當你更改運算子代碼時,重新整理你的自訂運算子以載入變更。 在選單的 「操作員」 標籤中,點擊 .
- 如果操作員保持不變
version,刷新會載入更新後的程式碼。 - 如果操作員有一個新的
version版本,畫布上的操作員會在重新整理後提示你升級至該版本(或保留目前版本)。
若要從 Lakeflow Designer 移除運算子,請從 .custom_operators.yaml 刪除其項目。 對於 uc-udf 和 uc-udtf 運算子,如果您不再需要,也可以使用 DROP FUNCTION 卸除底層的 Unity Catalog 函式。
權限
| 許可 | Purpose |
|---|---|
對 的.custom_operators.yaml。 |
找出操作者。 |
對 YAML 檔案的讀取權限(python-run-function僅限此權限)。 |
載入運算元定義。 |
| 在 Unity Catalog 函式上具有 EXECUTE 權限(僅限基於 Unity Catalog 函式的運算子)。 | 執行運算子。 |
| USE SCHEMA 在結構描述上(僅限於以 Unity Catalog 函式為基礎的運算子)。 | 存取建立函式的結構模式。 |
| 其他權限 | 根據您的營運商,使用者可能需要其他權限。 例如, USE CONNECTION 在 Unity 目錄連線中用於 HTTP API 呼叫。 |
故障排除
| Issue | 解決方案 |
|---|---|
| Operator 不會出現在 Lakeflow Designer 裡。 | 檢查 .custom_operators.yaml 是否存在,並且其中列出了你的函式或檔案路徑。 操作 python-run-function 員請確認檔案路徑及 YAML 檔案是否可存取。 |
| 架構驗證失敗。 | 請在 https://your-workspace.cloud.databricks.com/static/schemas/user-defined-operator-v0.1.0.json 根據官方結構描述驗證您的 YAML。 |
| 權限遭拒。 | 對於以 Unity Catalog 函式為基礎的運算子,請確認使用者對該函式具有 USE SCHEMA,並對該結構描述具有 EXECUTE。 對於 python-run-function 操作員,請確認使用者具有 YAML 檔案的讀取權限。 |
python-run-function 運算子在執行時失敗。 |
檢查函數簽名是否 run() 符合 def run(config, inputs, spark)。 確認程式碼中的埠名是否與 YAML 相符,且回傳字典鍵是否符合輸出埠 name 值。 |
| UDTF 回傳的型別不正確。 | UDTF 回傳類型必須明確;你無法參考輸入欄位類型。 |
其他資源
請探索以下教學:
| Example | 類型 | Description |
|---|---|---|
| Gmail 電子郵件寄件人 | python-run-function |
透過 Gmail 將 DataFrame 資料以 CSV 電子郵件附件形式傳送。 |
| 複利計算器 | uc-udf |
請使用複利公式計算未來投資價值。 |
| K-Means 叢集 | uc-udtf |
使用 scikit-learn 將資料分割成叢集。 |
| 發送 Slack 訊息 | uc-udf |
透過 Slack API 向 Slack 頻道發送通知。 |
| 所有 UI 小工具 | uc-udf |
參考運算子展示所有可用的 UI 元件。 |
要撰寫運算子邏輯,請參見 「撰寫 Lakeflow Designer 自訂運算子的邏輯」。 欲完整參考 YAML 架構,請參見 自訂 Operator YAML 參考。