创建 Fabric 用户数据函数项

用户数据函数使你能够创建可跨 Microsoft Fabric 和外部应用程序调用的可重用 Python 函数。通过在函数中集中业务逻辑，可以保持一致性、减少代码重复，并在整个组织中简化数据转换工作流。

使用用户数据函数，可以：

集中业务逻辑 - 编写函数一次，并从管道、笔记本、激活器规则和 Power BI 调用它们
无缝集成 - 通过 REST 终结点从任何应用程序或服务调用函数
加速开发 - 使用预生成的示例函数或通过 Python 编程模型创建自定义函数
保持一致性 - 确保跨所有工作负荷统一应用数据转换和业务规则

本快速入门介绍如何创建第一个用户数据函数项、从示例库添加函数、编写自定义函数并在 Fabric 门户中运行它们。最后，你有一个工作函数，用于演示产品数据的类别标准化。

你的成就

在本快速入门中，你将完成以下任务：

在工作区中创建用户数据函数项
添加和配置所需的 Python 库（如 pandas）
从示例库插入函数
使用适当的语法和修饰器编写自定义函数
测试和发布您的函数
在门户中运行函数并查看结果

先决条件

在其中一个支持的区域中，有一个 Microsoft Fabric 容量。如果没有 Fabric 容量，请启动免费的 Fabric 试用版。
分配给该容量的 Fabric 工作区

创建新的用户数据函数项

在工作区中，选择“+ 新建项”。
搜索并选择 “用户数据函数 ”磁贴。
输入用户数据函数项的名称，然后选择“创建”。
选择 “新建函数 文件”以创建新的示例函数。 hello_fabric Python 函数在代码编辑器中发布并加载。
函数资源管理器会显示已发布且已准备好调用的所有函数。由于函数 hello_fabric 已发布，因此可以从函数资源管理器中的函数列表中运行它。

从示例中添加新的函数

此示例演示如何从 “插入”示例 菜单中添加新函数。在本例中，我们将添加一个名为“使用 pandas 库操作数据”的函数，该函数将 pandas 库作为必要条件。

添加所需的库

请确保处于开发模式。
选择“库管理”，添加函数所需的库。
选择 “+从 PyPI 添加 ”，从公共 PyPI 存储库添加新库。
搜索并选择 pandas 库并选择版本。添加库后，它会自动保存在用户数据函数项中。
（可选）可以将库的版本 fabric_user_data_functions 更新到最新的可用版本。选择库旁边的铅笔图标进行更新。

注释

库 fabric_user_data_functions 默认包含，无法删除。要使用户数据函数正常工作，需要此库。需要为此 SDK 的任何将来版本更新此库的版本。
关闭 “库管理 ”窗格，返回到“用户数据函数”主页。

插入示例函数

选择“ 编辑 ”选项卡以在功能区菜单中打开更多编辑选项。
选择 插入示例>数据操作>使用 pandas 库进行数据操作。此操作会添加一个新函数，该函数使用 pandas 库来处理数据。
将示例插入编辑器后，你将看到新函数显示在 函数资源管理器 中，旁边有一个圆圈图标。此图标表示函数自上次发布以来发生了更改，这意味着需要发布更新。

编写自定义函数

从示例库添加函数后，可以直接在代码编辑器中编写自己的自定义函数。本部分介绍从头开始创建函数所需的语法和结构。

每个可运行函数都需要在函数定义之前使用@udf.function()修饰器。此修饰器在用户数据函数框架中将 Python 函数标记为可执行文件。基本语法为：

@udf.function()
def your_function_name(parameter: type) -> return_type:
    # Your function logic here
    return result

重要

参数名称必须使用 camelCase（例如， productName 而不是 product_name），并且所有参数均是必需的。有关完整的语法要求和限制，请参阅语法要求和限制。

下面是从原始销售数据标准化产品类别的完整示例：

# This function standardizes inconsistent product category names from different data sources

@udf.function()
def standardize_category(productName: str, rawCategory: str) -> dict:
    # Define category mappings for common variations
    category_mapping = {
        "electronics": ["electronic", "electronics", "tech", "devices"],
        "clothing": ["clothes", "clothing", "apparel", "fashion"],
        "home_goods": ["home", "household", "home goods", "furniture"],
        "food": ["food", "grocery", "groceries", "snacks"],
        "books": ["book", "books", "reading", "literature"]
    }
    
    # Normalize the input
    raw_lower = rawCategory.lower().strip()
    
    # Find the standardized category
    standardized = "other"
    for standard_name, variations in category_mapping.items():
        if raw_lower in variations:
            standardized = standard_name
            break
    
    return {
        "product_name": productName,
        "original_category": rawCategory,
        "standardized_category": standardized,
        "needs_review": standardized == "other"
    }

可以将此函数与现有的函数一起添加到代码编辑器中。该函数会显示在 函数资源管理器 中，其中包含一个圆图标，指示它需要发布。

编程模型关键概念

用户数据函数使用用户数据函数 Python 编程模型创建、运行、调试和修改各个函数。编程模型由 fabric-user-data-functions 包提供，该包在 PyPI 上公开提供，并预安装在用户数据函数项中。

创建第一个函数时，代码文件包括所需的导入语句：

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

有关编程模型的要点：

该 fabric-user-data-functions 包提供的 fabric.functions 模块，可在代码中作为 fn 导入。
该 fn.UserDataFunctions() 调用创建在用户数据函数项中定义和运行函数所需的执行上下文。
其他库，例如 logging ，可以编写用于调试和监视的自定义日志。

注释

import fabric.functions as fn语句和udf = fn.UserDataFunctions()行是函数正常运行所必需的。如果缺少这些行，函数 将不起作用 。

测试和发布您的函数

创建多个函数（示例 manipulate_data 函数和自定义 standardize_category 函数）后，可以一起测试和发布它们。

在开发模式下，可以在发布之前使用测试功能测试每个函数。通过测试，可以验证代码更改，而无需使其可用于外部调用。
准备好使函数可用时，请选择 “发布 ”以保存更改并更新所有函数。发布可能需要几分钟时间。
发布完成后，函数 资源管理器 列表中会刷新所有函数，并删除圆形图标。函数现已准备好：
- 在 “仅限运行” 模式下从门户运行
- 从另一个 Fabric 项（如管道、笔记本或激活器规则）调用
- 通过 REST 终端从外部应用程序进行调用

运行函数

创建、测试和发布所有函数后，现在可以切换到 “仅运行” 模式以执行它们并查看结果。

从门户右上角的模式选择器中选择 “仅运行”模式 。
选择将鼠标悬停在函数资源管理器列表中的函数上时显示的 “运行 ”图标。

运行示例函数

在 Functions 资源管理器中，将鼠标悬停在 manipulate_data 函数上。
选择将鼠标悬停在函数上时显示的 “运行 ”按钮。
此时会在屏幕右侧打开一个运行窗格。
在运行窗格中，你会看到参数名称数据，其类型为list。在文本框中输入以下 JSON 值：
```
[
 {
  "Name": "John",
  "Age": 22,
  "Gender": "male"
 }
]
```
选择运行窗格中的“ 运行 ”按钮（位于输入 JSON 数据的位置旁）以执行函数。
在运行窗格中的 “输出”（列表） 下查看结果和日志。输出以 JSON 格式的操作过的数据被显示为 pandas DataFrame。

运行自定义函数

现在，请尝试运行自定义 standardize_category 函数。

在 Functions 资源管理器中，将鼠标悬停在 standardize_category 函数上。
选择将鼠标悬停在函数上时显示的 “运行 ”按钮。
此时会在屏幕右侧打开一个运行窗格。
提供测试参数：
- productName： Laptop Computer
- rawCategory： tech
选择 “运行 ”并观察输出，该输出应将标准化类别显示为“电子”，并包含有关分类的元数据。

管理功能

创建并运行函数后，可以根据需要重命名或删除它们。所有管理操作都需要处于“开发”模式。

重命名函数

在 “开发”模式下，选择代码编辑器并更新函数的名称。例如，重命名 hello_fabric 为 hello_fabric1：

@udf.function()
def hello_fabric1(name: str) -> str:
   logging.info('Python UDF trigger function processed a request.')

   return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

更改名称后，选择“发布”来保存这些更改。
发布更改后，函数 资源管理器中会显示函数的新名称。

删除函数

若要删除函数，请在代码编辑器中选择函数代码并删除整个代码部分。发布更改，以从用户数据函数项中完全删除它。

例如，若要删除 hello_fabric 函数，请删除以下代码块：

@udf.function()
def hello_fabric(name: str) -> str:
    logging.info('Python UDF trigger function processed a request.')

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

删除代码后，可选择“发布”以保存更改。发布完成后，会在函数资源管理器中看到可用函数的更新列表。

Troubleshooting

如果在使用用户数据函数时遇到问题：

函数不会发布 - 检查代码中的语法错误。确保存在所有必需的导入（fabric.functions）和 udf = fn.UserDataFunctions() 行。
参数命名错误 - 请记住参数名称必须使用 camelCase（无下划线）。查看语法要求和限制。
库导入错误 - 验证所有必需的库是否通过库管理添加，并且版本是否与 Python 3.11 兼容。
函数未显示在 Functions 资源管理器中 - 请确保在添加或修改函数后发布了更改。

有关更多帮助，请参阅用户数据函数服务限制和注意事项。

创建第一个用户数据函数项后，请浏览以下资源以扩展技能：

在 Visual Studio Code 中创建 Fabric 用户数据函数项 - 了解如何使用完整的 IDE 支持在本地开发函数
了解用户数据函数编程模型 - 深入了解 Python SDK 和高级功能
从 Python 应用程序调用用户数据函数 - 通过 REST API 从外部应用程序调用函数
管理用户数据函数的库 - 了解高级库管理技术

反馈

此页面是否有帮助？

Last updated on 2026-01-22