Fabric 用户数据函数编程模型概述（预览版）

Fabric 用户数据函数编程模型是一种 SDK，它提供在 Fabric 中创作和发布可运行的函数所需的功能。 SDK 还支持与 Fabric 生态系统中的其他项（如 Fabric 数据源）无缝集成。 此库在 PyPI 中公开提供，并预安装在用户数据函数项中。

用户数据函数 SDK

用户数据函数项包含一个或多个可从 Fabric 门户、另一个 Fabric 项或使用提供的 REST 终结点从外部应用程序调用的函数。 每个函数都是 Python 脚本中的一种方法，它支持将参数传递给调用程序并返回输出。 用户数据函数编程模型包含以下组件：

• fabric.functions 库提供采用 Python 创建用户数据函数所需的代码。 创建新的用户数据函数项时，可以看到此库导入到第一个函数模板中。

• 方法 fn.UserDataFunctions() 提供执行上下文。 它将被添加到所有新用户数据函数项中的代码文件的开头，然后才是函数定义。

  示例：

  import datetime
  import fabric.functions as fn
  import logging
  
  udf = fn.UserDataFunctions()
  

• 每个函数都使用 @udf.function() 修饰器进行标识。 此修饰器将定义能否从门户或外部调用程序单独调用你的函数。

  可调用的函数示例

  # This is a hello fabric function sample that can be invoked from the Fabric portal, another Fabric item, or an external application.
  
  @udf.function()
  def hello_fabric(name: str) -> str:
      logging.info('Python UDF trigger function processed a request.')
      logging.info('Executing hello fabric function.')
  
      return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"
  

• 任何没有 @udf.function() 修饰器的 Python 方法都无法直接被调用。 它们只能从包含修饰器的函数进行调用，并可用作帮助程序函数。

  帮助程序函数示例

  # This is a helper function that can be invoked from other functions, but can't be invoked or run directly because it doesn't have the @udf.function() decorator
  
  def uppercase_name(name: str) -> str:
      return name.upper()
  

支持的输入类型

可以为函数定义输入参数，例如 str、int、float 等基元数据类型。支持的输入数据类型为：

支持的输出类型

支持的输出数据类型为：

与 Fabric 数据源的数据连接

使用此模块，可以引用数据连接，而无需在代码中编写连接字符串。 fabric.functions 库提供两种方法来处理数据连接：

• fabric.functions.FabricSqlConnection：支持在 Fabric 中使用 SQL 数据库，包括 SQL Analytics 终结点和 Fabric 仓库。
• fabric.functions.FabricLakehouseClient：支持使用湖屋，并通过一种方法连接到湖屋表和湖屋文件。

若要引用与数据源的连接，需要使用 @udf.connection 修饰器。 可以采用以下任何格式应用它：

• @udf.connection(alias="<alias for data connection>", argName="sqlDB")
• @udf.connection("<alias for data connection>", "<argName>")
• @udf.connection("<alias for data connection>")

@udf.connection 的参数为：

• argName，连接将在函数中使用的变量的名称。
• alias，使用“管理连接”菜单添加的连接的别名。
• 如果 argName 和 alias 的值相同，则可以使用 @udf.connection("<alias and argName for the data connection>")。

示例

# Where demosqldatabase is the argument name and the alias for my data connection used for this function
@udf.connection("demosqldatabase")
@udf.function()
def read_from_sql_db(demosqldatabase: fn.FabricSqlConnection)-> list:
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"

  # [...] Here is where the rest of your SqlConnection code would be.

  return results

使用 UserDataFunctionContext 获取调用属性

编程模型还包含 UserDataFunctionContext 对象。 此对象包含函数调用元数据，可用于为某些调用机制创建特定的应用逻辑。

下表显示了 UserDataFunctionContext 对象的属性：

ExecutingUser 对象包含以下信息：

若要访问 UserDataFunctionContext 参数，必须在函数定义的基础上使用以下修饰器：@udf.context(argName="<parameter name>")

示例

@udf.context(argName="myContext")
@udf.function()
def getContext(myContext: fabric.functions.UserDataFunctionContext)-> str:
    logging.info('Python UDF trigger function processed a request.')
    return f"Hello oid = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

使用 UserThrownError 引发句柄错误

开发函数时，可以使用 Python 编程模型中提供的 UserThrownError 方法引发预期的错误响应。 如果用户提供的输入无法通过业务验证规则，则可以使用此方法。

示例

import datetime

@udf.function()
def raise_userthrownerror(age: int)-> str:
    if age < 18:
        raise fn.UserThrownError("You must be 18 years or older to use this service.", {"age": age})

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

UserThrownError 方法采用以下两种参数：

• Message：此字符串将作为错误消息返回给调用此函数的应用程序。
• 属性字典，这些属性将返回到调用此函数的应用程序。

后续步骤

• 创建 Fabric 用户数据函数项
• 用户数据函数示例