教程：创建跨事务任务流（预览版）

2025-05-20

在此端到端教程中，你将创建一个跨事务分析任务流，该任务流将写回 Fabric 中的 SQL 数据库。为了帮助说明端到端的增强体验，我们专注于数据注释场景的事务分析任务流程。

本教程中，您将学习如何：

在 Fabric 中创建 SQL 数据库。
配置可写回 SQL 数据库的用户数据函数。
将用户数据函数与 Power BI 报表集成。

如果没有现有的 Fabric 容量，请启动 Fabric 试用版。

注释

跨事务分析任务流功能目前以公共预览版提供。

先决条件

在 Power BI 和 Fabric 中启用所需的预览功能。
使用管理门户租户设置在 Fabric 中启用 SQL 数据库。
Power BI Desktop。如果设备上未安装 Power BI Desktop，请按照 “获取 Power BI Desktop”中的说明作。

概述

创建一个转译分析任务流需要三个步骤来实现自动化场景：

存储数据

从现有 Fabric 数据源开始。在本教程中，我们使用包含示例数据的 SQL 数据库。
开发数据

编写从 Power BI 报表调用的 Fabric 用户数据函数。此函数可以执行任意数量的操作，从编辑数据源报表到发送通知并在审批管道中创建工作项。在本教程中，我们将创建一个用户数据函数，该函数采用新产品说明并将其写入 SQL 数据库。
可视化数据

创建一个 Power BI 报表，该报表显示调用数据函数的源数据和交互式元素。在本教程中，我们使用文本切片器从用户收集产品说明并将其发送到用户数据函数。然后，报表将刷新以显示更新后的表。

创建 SQL 数据库

此方案使用 SQL 数据库中的示例 AdventureWorksLT 数据集。

请按照Fabric 门户中“创建 SQL 数据库”中的步骤操作。

记下向 SQL 数据库提供的名称。本教程稍后会用到此值。
创建数据库后，选择 “示例数据 ”选项，将 AdventureWorksLT 示例数据加载到空数据库中。

创建用户数据函数

在工作区中创建用户数据函数。

在 Power BI 或 Fabric 中导航到所选工作区。
选择“新建项”。
从“开发数据”组中选择“用户数据函数”（预览版）。
提供新用户数据函数的名称，例如 sqlwriteback，然后选择“ 创建”。

记下你使用的名称和工作区名称。本教程稍后会用到这两个值。
选择 “新建函数”。

连接到 SQL 数据库

将用户数据函数连接到之前创建的 SQL 数据库。在继续作之前，请确保你对 SQL 数据库具有访问权限。

在新用户数据功能页面上选择管理连接。
选择 “添加数据连接”。
选择之前创建的 AdventureWorksLT SQL 数据库，然后选择 “连接”。
创建连接时，会自动为连接创建别名。记下别名值，以便在教程后续步骤中使用。
关闭 “连接” 页以返回到用户数据函数。

添加函数代码

在用户数据函数中添加代码，以便将数据写入 SQL 数据库 AdventureWorksLT 示例的 [SalesLT].[ProductDescription] 表中。

默认情况下，用户数据函数将 pyodbc 用于 SQL 连接，我们建议使用此方案的库。

若要将用户数据函数连接到 Power BI 按钮，该函数必须返回字符串。

将用户数据函数中的默认代码替换为以下示例：

import fabric.functions as fn
import uuid

udf = fn.UserDataFunctions()

@udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>") 
@udf.function() 

# Take a product description and product model ID as input parameters and write them back to the SQL database
# Users will provide these parameters in the PowerBI report
def write_one_to_sql_db(sqlDB: fn.FabricSqlConnection, productDescription: str, productModelId:int) -> str: 

    # Error handling to ensure product description doesn't go above 200 characters
    if(len(productDescription) > 200):
        raise fn.UserThrownError("Descriptions have a 200 character limit. Please shorten your description.", {"Description:": productDescription})

    # Establish a connection to the SQL database  
    connection = sqlDB.connect() 
    cursor = connection.cursor() 

    # Insert data into the ProductDescription table  
    insert_description_query = "INSERT INTO [SalesLT].[ProductDescription] (Description) OUTPUT INSERTED.ProductDescriptionID VALUES (?)" 
    cursor.execute(insert_description_query, productDescription) 

    # Get the result from the previous query 
    results = cursor.fetchall() 

    # In real-world cases, call an API to retrieve the cultureId
    # For this example, generate a random Id instead
    cultureId = str(uuid.uuid4()) 

    # Insert data into the ProductModelProductDescription table 
    insert_model_description_query = "INSERT INTO [SalesLT].[ProductModelProductDescription] (ProductModelID, ProductDescriptionID, Culture) VALUES (?, ?, ?);" 
    cursor.execute(insert_model_description_query, (productModelId, results[0][0], cultureId[:6])) 

    # Commit the transaction 
    connection.commit() 
    cursor.close() 
    connection.close()  

    return "Product description was added"

在示例中查找以下代码行：

@udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>")

请将别名占位符替换为上一部分的别名值。

可以再次打开 “管理连接 ”页以查看连接别名。

测试示例代码

若要测试到目前为止的示例代码，请使用本节中的步骤。

选择发布。
发布函数后，将鼠标悬停在函数资源管理器菜单上的write_one_to_sql_db函数上，然后选择“运行”图标。
在 “运行 ”页上，提供两个必需参数的示例数据：
- productDescription： string
- productModelId：介于 1 和 127 之间的整数
选择运行。
查看函数输出和生成的日志。
完成测试后，关闭 “运行 ”页。

如果在运行示例代码时收到任何错误，请检查帐户是否有权访问数据库。

授予用户权限（可选）

如果其他用户与调用此函数的 Power BI 报表交互，请授予他们 执行函数 权限。

在函数页上，选择“ 共享”。
选择 “创建”和“发送链接 ”弹出窗口的第一个框。
从“其他权限”列表中选择“执行函数”和“查看函数日志”，然后选择“应用”。
在 “输入名称或电子邮件地址 ”框中，提供想要对此函数具有权限的用户或组。
选择发送。

创建 Power BI 报表

在本部分中，将创建一个 Power BI 报表，用于从上一部分创建的 SQL 数据库拉取数据。

连接到 SQL 数据库

连接到 SQL 数据库，将其用作报表的数据源。

在 Power BI Desktop 中，创建新的报表。
选择 OneLake 目录>SQL 数据库。
在 OneLake 目录 窗口中，选择在上一部分创建的数据库。例如 ，AdventureWorksLT。然后，选择连接。
按照任何提示向数据库进行身份验证。
成功连接到数据库后，将打开 导航器 窗口。选择下表，然后选择“ 加载”：
- SalesLT.ProductDescription
- SalesLT.ProductModel
- SalesLT.ProductModelProductDescription
出现提示时，选择 DirectQuery 作为连接模式，然后选择“ 确定”。

DirectQuery 模式是一种实时连接，使报表能够刷新数据并反映任何数据修改。有关详细信息，请参阅 Power BI 中的 DirectQuery。

生成 Power BI 报表

在本部分中，使用加载到 Power BI 报表中的数据生成视觉对象。

在“数据”菜单中，选择以下列：
- SalesLT.ProductModel > Name
- SalesLT.ProductModelProductDescription > ProductModelID
在您的报表窗口中会出现一个双列表。
在 “可视化效果 ”菜单中，选择 “文本切片器” 图标。

小窍门

如果未看到文本切片器图标，请确保在 Power BI Desktop 中启用了 文本切片器 预览功能。有关详细信息，请参阅所需的预览功能。

文本切片器视觉对象显示在报表窗口中。
选择文本切片器并使用“格式视觉对象>常规>标题”选项为文本切片器提供以下标题： Write a new product description
在任务栏上，选择 “插入 ”菜单，并向报表添加空白按钮。拖动文本切片器下的按钮。
在格式按钮窗格中选择该按钮，并展开操作选项。将“动作”单选按钮调为“开”。

为按钮提供以下值：

参数	价值
类型	选择数据函数
工作空间	选择包含您在上一部分中创建的用户数据函数的工作区。
函数集	选择包含数据函数的函数集。例如，sqlwriteback。
数据函数	选择您的数据函数。例如， write_one_to_sql_db。

小窍门

如果未看到 “数据函数 ”选项，请确保在 Power BI Desktop 中启用了 Translytical 任务流 预览功能。

如果确实看到 “数据函数 ”选项，但看不到用户数据函数，请确保数据函数返回字符串。

选择数据函数后，将显示更多参数来表示函数采用的参数。提供以下值：

参数	价值
productDescription	从报表中选择文本筛选器，编写新的产品说明。
productModelId	选择条件格式（fx）按钮。新窗口将打开。对于格式样式参数，请保留默认字段值。对于应基于哪个字段？参数，请选择所有数据>SalesLT.ProductModel>，ProductModelID。
汇总	选择最大值。

选择确定以完成操作配置。操作详细信息应如以下示例所示：
选择该按钮，然后在“格式”按钮窗格中展开“样式”选项。将文本单选按钮设为打开，并标记为 Enter。
在样式选项中，将应用设置切换到加载选项。

加载状态是可用于数据函数按钮的唯一状态，可用于定义数据函数运行时显示的样式选项。
展开 “文本 ”菜单，并将按钮文本值 Submitting替换为。
展开 “图标 ”菜单。

默认情况下，数据函数按钮具有加载状态的 旋转图标 类型。
使用以下更改调整图标样式：

参数价值

填充将左侧填充更改为 20 px。

图标大小 将默认 的“自动” 值替换为 20。
在 “可视化效果 ”窗格中，选择 “表” 图标以插入新表。
在数据窗格中选择以下列，将这些列添加到表中：
- SalesLT.ProductModel > Name
- SalesLT.ProductDescription > Description
- SalesLT.ProductDescription > ModifiedDate

参数	价值
填充	将左侧填充更改为 `20 px`。
图标大小	将默认的“自动” 值替换为 `20`。

可选的报表修改

与任何 Power BI 报表一样，可通过多种方式自定义外观并改进此报表的功能。请考虑以下一些选项：

将标题添加到两个表。例如，选择产品和产品说明。
提交新产品说明后，将文本切片器设置为自动清清。为此，请选择触发用户数据函数的按钮。在“格式”按钮>操作菜单中，将“自动清除”开关设置为“打开”。
在触发用户数据函数后，取消报告的自动刷新。在这种情况下，刷新数据并查看新的产品描述出现在表格中会很有帮助。在其他方案中，可能不需要或想要刷新报表。若要关闭此设置，请选择触发用户数据函数的按钮。在“格式”按钮>操作菜单中，将“在成功结果后刷新报告”的切换设置为“关闭”。

运行事务性任务流

可以在 Power BI Desktop 中测试传译型任务流的功能。但是，如果想要查看最准确的最终用户体验，请向 Power BI 服务发布报表并在 Web 中对其进行测试。

发布报表

你在 Power BI Desktop 中生成了报表。在本部分中，将发布报表，以便用户可以在 Web 门户中与其交互。

在 “开始 ”工具栏菜单中，选择“ 发布”。
选择要在其中发布此报表的 Power BI 工作区，然后选择“ 选择”。
报表发布完成后，选择打开 <REPORT_NAME.pbix> 的链接，在 Power BI 中查看。
小窍门

在 Power BI Web 门户中打开报表时，可能会看到一条错误，指出 数据源缺少凭据，无法访问。若要解决此错误，请使用以下步骤：
1. 打开报表的语义模型并导航到“文件>设置”。
2. 展开 数据源凭据 设置（如果尚未设置）。
3. 选择“编辑凭据”。
4. 从下拉菜单中选择 身份验证方法 。例如， Basic 采用用户名和密码， OAuth2 支持使用当前帐户进行单一登录。
5. 提供所需的信息（如果有），然后选择 “登录”。

现在，您可以在 Power BI 服务中的 Power BI 报告中使用一个包含事务分析特性的任务流。

运行事务分析任务流

在本部分中，将在 Power BI Web 门户中与报表进行交互，以测试生成的跨事务任务流。

只有有权触发数据函数的用户才能使用此功能。任何未经授权的用户都会收到错误响应。

在 Power BI 中打开报表。
从列出名称和 ID 的产品表中选择产品。此选择将上下文传递给文本切片器，以确定要更新的产品。您还会看到产品说明表已过滤，以显示所选产品的所有当前描述。
在输入文本框中编写新产品说明。
选择箭头图标或使用 Tab 键提交输入。选择产品并提供说明后，可以看到按钮切换到已启用状态。
选择用于运行用户数据函数的按钮。

如果事务性任务流正常工作，则会收到一条消息，指出 您报表上的操作已成功提交。产品说明表将刷新以显示新说明。

如果在跨分析任务流中出现错误，你会收到一条消息，指出 出现问题。选择 “查看详细信息 ”以获取有关失败原因的详细信息。运行不成功的函数的一些常见原因包括：

数据验证：输入值不符合用户数据函数中定义的数据验证规则。
超时错误：函数或进程花费的时间比允许的时间要长。
设置不当：配置报表元素时出错（通常是按钮）可能会导致任务流失败或产品意外结果。
未经授权的用户：用户无权触发数据函数。

后续步骤

若要获取可合并到工作流中的跨任务流的想法，请参阅 Translytical 任务流示例。
若要了解有关将数据函数按钮集成到 Power BI 报表的选项的详细信息，请参阅 Power BI 中的“创建数据函数”按钮。

通过

教程：创建跨事务任务流（预览版）

先决条件

概述

创建 SQL 数据库

创建用户数据函数

连接到 SQL 数据库

添加函数代码

测试示例代码

授予用户权限（可选）

创建 Power BI 报表

连接到 SQL 数据库

生成 Power BI 报表

可选的报表修改

运行事务性任务流

发布报表

运行事务分析任务流

后续步骤

反馈

其他资源