通过

项目引用变量类型（预览版）

为了提高灵活性和可伸缩性，我们将介绍高级变量以及现有的基本变量类型。 这些高级变量旨在满足关键要求，例如参数化外部连接和内部连接（例如 Snowflake、AWS、OneLake）。

项引用变量是构造变量库中用于通过存储其工作区 ID 和项 ID 来保存对现有 Fabric 项（如 lakehouse、Notebook 或数据管道）的引用的高级变量类型。 这种类型的变量支持内部连接参数化，使开发人员能够基于部署阶段或工作区上下文动态将项链接到特定 Fabric 项。

如何使用

项引用变量可以像变量库中的其他变量一样使用。

  1. 登录到 Microsoft Fabric
  2. 导航到工作区和变量库
  3. 在顶部，选择“+ 新建变量”
  4. 提供变量的名称，为类型选择 项引用 ，然后单击 ... 以选择值
  5. 这将打开一个对话框以选择所需的项。 你将看到你拥有权限的所有项，可供选择。 使用左侧的资源管理器按工作区筛选列表。 使用右上角的筛选器按类型进行筛选。

可用于项引用的项的屏幕截图。 6. 选择后，它将在 varlib 页面上显示为只读组件，其中显示了项的名称。

项目引用的屏幕截图。

如果需要编辑项引用或需要仔细检查该值：

  • 若要查看其他详细信息，请单击该值
  • 若要编辑此值或其他值集的值，请单击值旁边的按钮。

项引用弹出窗口的屏幕截图。

工作原理

项目引用变量的值实际上是一个静态指针，指向由 工作区 ID + 项目 ID 标识的 Fabric 项目。 该值存储为与目标项目的工作区及项目本身对应的一对 GUID。 例如，引用可能在内部存储为：

  • WorkspaceID = aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
  • ItemID = 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

这两个 ID 一起唯一标识引用的项。

使用项引用时，请记住以下几点：

  • 项引用支持内部连接参数化，使开发人员能够根据部署阶段或工作区上下文动态将项链接到特定 Fabric 资源。
  • 引用是静态的，指向特定项，不会跨环境自动调整。
  • 对于特定阶段的变体，请使用值集，其中每个集可以指向不同的静态元素（例如，每个阶段的不同湖仓）。
  • 值集中的所有值 都应 具有相同的项类型，以确保兼容性并防止运行时错误。 但是，我们不强制跨值集具有相同的项类型。

支持的项目

下面是当前使用项目引用支持的项目列表：

项目参考笔记本的屏幕截图。

注释

不支持笔记本。%%configure

局限性

目前，只能引用结构项目和语义模型。 目前不支持其他 Power BI 项，如 Datamarts、数据流 Gen1。

创建/使用项引用所需的权限

使用项引用变量涉及两层权限：

  • 创建/编辑 - 尽管任何工作区参与者都可以修改变量值，但项目引用变量仅允许用户将值设置为他们有读取权限的项目。 这适用于任何值、默认活动值集或其他值集。 请注意，在保存变量库项期间，即使这些值保持不变，也会对保存项的用户的项目引用变量的活动值执行权限检查。
  • 使用项引用变量 - 在创建或更新一个消费者项中变量的引用时，用户无法设置对项引用变量的引用，除非他们至少拥有活动值集中该项的 READ 权限。

权限验证

在以下用例中触发权限验证：

  • 编辑包含项引用变量的变量库项时，我们会验证引用的项是否存在，并且用户对这些项至少拥有读取权限，以适用于活动值集中的所有项引用值。以下是相关场景：

  • UI - 在保存变量库项期间，会对保存该项的用户项目引用变量的当前值执行权限检查，即使这些值保持不变。

  • API/Git 更新 - 在更新期间完成权限验证，如果没有对已更新工作区的 Item ref 的活动值具有读取权限，则失败。

  • 部署 - 如果对 Item ref 的活动值的目标工作区没有读取权限，变量库项的部署将失败。

  • 在“变量库”页（仅限 UI）查看项目引用的附加详细信息：有权访问变量库（WS 查看器或更高级别）的用户若没有访问引用项变量中某个项目的权限，将不会在 UI 中看到该项目的详细信息。 相反，他们将看到带有悬停消息的项 ID，而不是详细信息组件。

权限的屏幕截图。

  • 创建/编辑项引用变量

    • UI - 更新任何值集的值（默认或其他值）时，用户可以从列表中选择项目，其中仅显示他至少具有读取权限的项目。
    • API/Git 更新或部署 - 请参阅上面的编辑变量库项。

  • 在消费者项目中使用项目引用变量

    • UI - 创建对变量的引用 - 在项目中通过“选择变量”UI 对话框（如在 Lakehouse 和 Data Pipeline 中的快捷方式）创建对“项目引用”变量的引用时，需验证创建引用的用户对“项目引用”变量中的项目至少具有读取权限（验证仅适用于活动值）。 否则，用户只看到项的 ID。

跨 CI/CD 管道和部署阶段的行为

变量库通过项引用变量在开发、测试和生产等不同环境中实现 Fabric 内容的 CI/CD，从而支持特定阶段的配置。 请记住以下几点：

静态引用

  • 项目引用与特定的工作区和项目ID绑定。
  • 部署到新阶段，除非手动更新，否则这些引用仍指向原始工作区。
  • 为每个阶段使用多个值集，并手动或通过 API 脚本激活正确的值集。

有关详细信息，请参阅 变量库中的值集。

Git 和 API 中的表示形式

变量库作为代码进行管理。 使用 Git 或 REST API 时，项引用变量具有明确的 JSON 格式。 所有变量都显示在变量库的定义文件中（存储在 Git 中，通常 .json），其中列出了名称、类型和值等属性。

对于项引用（静态）变量，该值是工作区和项 ID 的结构化数据。 示例：


{
 "name": "MyDataLake",
 "note": "",
 "type": "ItemReference",
 "value": {
  "itemId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "workspaceId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
 }
}

通过 API 工作时，请记住以下事项：

  • 仅存储 ID;名称和元数据在运行时检索或缓存在 Fabric 中。
  • 使用 API 创建或更新时，您需要提供工作区和项目 ID。 无效 ID 会导致错误。

相关内容

  • Last updated on