共用方式為

為使用者資料函式產生呼叫碼

一旦你發佈了使用者資料函式，就可以從 Fabric 項目或外部應用程式呼叫它們。 與其從零開始撰寫呼叫程式碼，不如使用 「產生呼叫碼 」功能自動建立現成可用的程式碼範本。

根據你的整合情境選擇程式碼產生選項：

  • Fabric Notebooks 程式碼 （Python）-用於在 Fabric Notebook 內調用函式，這是與 Fabric 項目整合的一種方式。 至於其他 Fabric 項目，如 Pipelines 和 Activator，請參閱 整合文件。
  • 用戶端應用程式程式碼 （Python、C#、Node.js）——透過每個函式所暴露的獨特 REST 端點，從外部應用程式呼叫你的函式。 這能與網頁應用程式、服務或 Fabric 以外的任何系統整合。
  • OpenAPI 規範 （JSON、YAML）— 用於 API 管理平台、AI 代理或產生用戶端 SDK。 利用它整合你的功能與 Azure API 管理、配置 AI 系統，或為外部應用程式生成函式庫。

先決條件

在產生呼叫碼之前，你需要：

  • 已發表的使用者資料功能項目，至少包含一個函數
  • 在 Fabric 入口網站中存取使用者資料功能選項
  • 至少要有執行使用者資料功能項目上的權限來產生和使用調用代碼

生成 Fabric 筆記本的程式碼

當與 Fabric 專案整合時，使用此選項從 Fabric 筆記本中調用功能。 產生的程式碼使用內建 mssparkutils.userDataFunction 的工具，提供一種簡單的方式來呼叫函數，無需管理認證或端點。 這非常適合在 Fabric 環境中進行資料處理工作流程、探索性分析及機器學習流程。

  1. 在 Fabric 入口開啟你的使用者資料功能項目。

  2. 在 「主頁 」分頁，選擇 產生呼叫代碼>客戶端代碼。

  3. 在 「呼叫來源」中，從下拉選單選擇 筆記本 。

  4. 選擇你想呼叫的函式名稱。

  5. 程式碼是用 Python 自動產生的。 （Python 是唯一可用於筆記本調用程式碼的語言。）

    螢幕擷取畫面，顯示產生的筆記本調用程式碼。

  6. 複製產生的程式碼片段。

  7. 把它貼到你的 Fabric 筆記本的新儲存格裡。

  8. 用你的實際數值更新函數參數。 產生的程式碼包含註解，說明該在哪裡更新：

    # UPDATE BELOW: Update the request body based on the inputs to your function
myFunctions.hello_fabric(name = "string")

  9. 執行程式碼區塊來調用你的函數。

欲了解更多資訊，請參閱 Fabric Notebook 使用者資料功能工具。

為客戶端應用程式產生程式碼

在與外部應用程式整合時，請使用此選項，透過每個功能所公開的獨特 REST 端點，呼叫您的功能。 產生的程式碼包含使用 Microsoft Entra ID 設定的認證，並處理 HTTP 請求/回應流程。 這讓你能從網頁應用程式、行動應用程式、微服務或任何 Fabric 環境外的系統調用 Fabric 功能。

  1. 在 Fabric 入口開啟你的使用者資料功能項目。

  2. 在 「主頁 」分頁，選擇 產生呼叫代碼>客戶端代碼。

  3. 在 「呼叫來源」中，從下拉選單選擇 「用戶端應用程式 」。

  4. 選擇你想呼叫的函式名稱。

  5. 選擇你的程式語言：

    • Python（編程語言）
    • C#
    • Node.js

    顯示用戶端程式碼輸出的螢幕擷取畫面。

  6. 複製產生的程式碼並加入你的應用程式。

  7. 檢視程式碼結構：

    • 認證 - 用於 InteractiveBrowserCredential 取得憑證（僅限開發/測試）
    • 端點 URL - 你特定函式的唯一 REST 端點
    • 請求本體 - 包含函式期望的輸入參數

  8. 更新 request_body 該區塊，顯示你的實際參數值。 產生的程式碼包含註解，說明該在哪裡更新：

    # UPDATE HERE: Update the request body based on the inputs to your function 
request_body = {
    "name": "string"
}

  9. 對於生產應用程式，請將身份驗證代碼替換為正確的 Microsoft Entra ID 應用程式註冊。 產生的程式碼包含警告及生產驗證指引連結。

完整攻略包括生產驗證設定，請參見 「從 Python 應用程式調用使用者資料函數」。

產生 OpenAPI 規範

當你需要將功能整合到 API 管理平台、AI 代理，或為外部應用程式產生客戶端 SDK 時，請使用此選項來建立 OpenAPI 規範。 OpenAPI 規範提供了您函式的 REST 端點機器可讀描述，讓工具與系統能輕鬆發現並以程式方式整合您的函式。

  1. 在 Fabric 入口開啟你的使用者資料功能項目。

  2. 在 「主頁 」分頁，選擇 產生呼叫代碼>OpenAPI 規範。

  3. 在 「產生 OpenAPI 規範 」對話框中，選擇您的輸出格式：

    • JSON
    • YAML

    顯示 OpenAPI 規格的螢幕擷取畫面。

  4. 複製產生的規格。 規範內容包括：

    • 所有已發佈的功能都包含在使用者資料功能項目中
    • 每個函式的請求與回應結構
    • 認證要求（承載憑證）
    • 標準 HTTP 錯誤回應（400， 401， 403， 408， 413， 500）
    • 功能摘要與描述（來自 docstrings）

用 docstrings 改善 OpenAPI 輸出

你的 OpenAPI 規範品質取決於函式程式碼中的文件內容。 當像 Azure API 管理、AI 代理或 API 文件工具等系統使用你的 OpenAPI 規格時，他們依賴清晰的描述來理解你的函式功能。

OpenAPI 產生器會自動從你的函式文件串中擷取資訊。 將這些屬性加入函式，以建立完整的 API 文件：

  • 摘要 - 出現在 API 目錄與高階檢視中的一行說明
  • 說明 - 詳細說明函式的功能、預期輸入及回傳內容

範例功能並附有完整文件：

@udf.function()
def hello_fabric(name: str) -> str:
    """
    Summary: A Python function that prints your name and the time.
    Description: This function takes a string input and concatenates it with the current time 
    to give you a warm welcome to User Data Functions. Returns a string and provides a log entry.
    """
    logging.info('Python UDF trigger function processed a request.')
    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

當你產生 OpenAPI 規範時，這些 docstring 值會填入 OpenAPI 模式中的summary及description欄位，讓開發者和系統更容易理解如何使用你的函數。

產生程式碼的常見用途

產生呼叫代碼後，你可以用它將函式整合到不同的情境中：

布料商品整合：

  • 從筆記本中呼叫函數，用於資料處理、機器學習及探索性分析
  • 在管線中安排功能以進行資料轉換工作流程
  • 根據啟動器規則觸發功能，以回應即時事件

外部應用程式整合：

  • 透過用戶端應用程式碼呼叫網頁應用程式、行動應用程式或微服務的功能
  • 將 OpenAPI 規範匯入 Azure API 管理或其他 API 閘道以進行集中管理
  • 使用 OpenAPI Generator 產生客戶端 SDK，以確保跨多系統的整合一致
  • 配置 AI 代理，使用 OpenAPI 規範來發現並呼叫你的函式
  • 使用 Postman 或 Swagger UI 等工具測試與驗證功能

相關內容

  • Last updated on