Git 集成入门

本文将引导你在 Microsoft Fabric 的 Git 集成工具中完成以下基本任务：

• 连接到 Git 存储库
• 提交更改
• 从 Git 更新
• 断开与 Git 的连接

建议在开始之前阅读 Git 集成概述。

先决条件

若要将 Git 与 Microsoft Fabric 工作区集成，需要在 Fabric 和 Git 中设置以下先决条件。

Fabric 先决条件

若要访问 Git 集成功能，需要以下项之一：

• Power BI Premium 许可。 Power BI Premium 许可证仅支持所有 Power BI 项。
• Fabric 容量。 需要使用结构容量才能使用所有受支持的 Fabric 项。 如果没有，可以注册免费试用版。

此外，必须从管理员门户启用以下租户开关：

• 用户可以创建 Fabric 项
• 用户可以将工作区项与 Git 存储库同步
• 仅适用于 GitHub 用户：用户可以将工作区项与 GitHub 存储库同步

租户管理员、容量管理员或工作区管理员可以根据组织的设置启用这些开关。

Git 先决条件

Azure DevOps 和 GitHub 目前支持 Git 集成。 若要使用 Git 与 Fabric 工作区集成，需要在 Azure DevOps 或 GitHub 中满足以下先决条件：

Azure DevOps 限制

• 向使用 Fabric 工作区的同一用户注册的活动 Azure 帐户。 创建一个免费帐户。
• 访问现有存储库。

GitHub 限制

• 一个有效的 GitHub 帐户。 创建 GitHub 帐户。

• 以下个人访问令牌之一：

  • 存储库权限下具有“内容”读取和写入权限的精细令牌（推荐使用）：

    

    若要将此令牌用于 GitHub Enterprise，请按照以下说明进行操作。

  • 创建启用了存储库作用域的 GitHub 经典令牌：

    

将工作区连接到 Git 存储库

连接到 Git 存储库

只有工作区管理员可以将工作区连接到存储库，但连接后，具有权限的任何人都可以在工作区中工作。 如果你不是管理员，请向管理员请求有关连接的帮助。 若要将工作区连接到 Azure 或 GitHub 存储库，请执行以下步骤：

1. 登录到 Fabric 并导航到要连接的工作区。

2. 转到“工作区设置”

   

3. 选择“git 集成”。

4. 选择 Git 提供程序。 目前支持 Azure DevOps 和 GitHub。

Azure DevOps 连接

如果选择 Azure DevOps，请选择“连接”以自动登录到 Azure Repos 帐户，该帐户已注册到登录到 Fabric 的 Microsoft Entra 用户。

GitHub 连接

如果选择 GitHub，则需登录到 GitHub 帐户。
如果是首次从 Fabric 登录，请选择“添加帐户”，或者选择列出的帐户之一。 登录后，选择“连接”，允许 Fabric 访问 GitHub 帐户。

如果是首次连接，则需授权 GitHub 用户。 提供以下信息：

• 显示名称 – 对于每个 GitHub 用户必须是唯一的
• 个人访问令牌 - 经典或精细的个人访问令牌
• 存储库 URL（可选）– 如果不输入 URL，可以连接到有权访问的任何存储库。 如果输入 URL，则只能连接到此存储库。

连接到工作区

如果工作区已连接到 GitHub，请按照连接到共享工作区的说明进行操作。

Azure DevOps 分支连接

1. 在下拉菜单中，指定要连接到的分支的以下详细信息：

   注意

   一次只能将一个工作区连接到一个分支和一个文件夹。

   • 组织
   • 项目
   • Git 存储库。
   • 分支（使用下拉菜单选择现有分支，或选择“+新建分支”以创建新分支。一次只能连接到一个分支。）
   • 文件夹（键入现有文件夹名称或输入名称以创建新文件夹。如果将文件夹名称留空，则会在根文件夹中创建内容。一次只能连接到一个文件夹。）

GitHub 分支连接

1. 在下拉菜单中，指定要连接到的分支的以下详细信息：

   注意

   一次只能将一个工作区连接到一个分支和一个文件夹。

   • 存储库 URL。 如果使用作用域令牌连接到 GitHub，则 URL 会自动填充，并且只能连接到该存储库。
   • 分支（使用下拉菜单选择现有分支，或选择“+新建分支”以创建新分支。一次只能连接到一个分支。）
   • 文件夹（键入现有文件夹名称或输入名称以创建新文件夹。如果将文件夹名称留空，则会在根文件夹中创建内容。一次只能连接到一个文件夹。）

选择“连接并同步”。

在初始同步期间，如果工作区或 Git 分支为空，则内容将从非空位置复制到空位置。 如果工作区和 Git 分支都有内容，系统会询问同步的方向。 有关此初始同步的详细信息，请参阅连接和同步。

连接后，工作区将显示有关源代码管理的信息，该信息允许用户查看连接的分支、分支中每个项的状态以及上次同步的时间。

若要使工作区与 Git 分支保持同步，请将在工作区中所做的任何更改提交到 Git 分支，并在任何人创建新的 Git 分支提交时更新工作区。

将更改提交到 git

成功连接到 Git 文件夹后，像往常一样编辑工作区。 保存的任何更改仅保存在工作区中。 准备就绪后，可以将更改提交到 Git 分支，也可以撤消更改并还原到以前的状态。 阅读关于提交的详细信息。

提交到 Git

若要将更改提交到 Git 分支，请执行以下步骤：

1. 转到工作区。

2. 选择“源代码管理”图标。 此图标显示未提交的更改数。

3. 选择“源代码管理”面板的“更改”。 此时会显示一个列表，其中包含已更改的所有项，以及一个图标，指示该项是新项、已修改项、冲突项 还是已删除项。

4. 选择想要删除的项目。 若要选择所有项目，检查顶部框。

5. 在框中添加注释。 如果不添加注释，则会自动添加默认消息。

6. 选择“提交”。

   

提交更改后，已提交的项将从列表中删除，工作区将指向同步到的新提交。

成功完成提交后，所选项的状态将从“未提交”更改为“已同步”。

撤消保存的更改

将更改保存到工作区后，如果决定不想将这些更改提交到 git，则可以撤消更改，并将这些项还原到以前的状态。 若要撤消更改，请执行以下步骤：

1. 转到工作区。

2. 选择“源代码管理”按钮。 此按钮还显示未提交的更改数。

3. 选择“源代码管理”面板的“更改”。 此时会显示一个列表，其中包含已更改的所有项，以及一个图标，指示更改项是新项、已修改项、冲突项 还是已删除项。

4. 选择要撤消的更改。

5. 选择“撤消”。

   

6. 再次选择“撤消”以确认。

   

工作区中的选定项还原上次同步工作区时的状态。

重要

如果删除某个项，然后撤消更改，则会重新创建该项，并且某些元数据可能会丢失。 例如，敏感度标签不会保留，应重置，并且项的所有者设置为当前用户。

从 Git 更新工作区

每当有人向连接的 Git 分支提交新更改时，相关工作区中都会显示一条通知。 使用“源代码管理”面板可拉取最新更改、合并或还原到工作区并更新实时项。 阅读有关更新的详细信息。

若要更新工作区，请执行以下步骤：

1. 转到工作区。
2. 选择“源代码管理”图标。
3. 选择“源代码管理”面板的“更新”。 此时会显示一个列表，其中包含自上次更新以来分支中已更改的所有项。
4. 选择“全部更新”。

成功更新后，将删除项列表，工作区将指向同步到的新提交。

成功完成更新后，项的状态将更改为“已同步”。

断开工作区与 Git 的连接

只有工作区管理员可以断开工作区与 Git 存储库的连接。 如果你不是管理员，请向管理员请求有关断开连接的帮助。 如果你是管理员并想要断开存储库的连接，请执行以下步骤：

1. 转到“工作区设置”
2. 选择“git 集成”。
3. 选择“断开工作区连接”
4. 再次选择“断开连接”进行确认。

权限

可以对工作区执行的操作取决于在工作区和 Git 存储库中拥有的权限。 有关权限的更详细讨论，请参阅权限。

注意事项和限制

常规 Git 集成限制

• Fabric 中的身份验证方法必须至少与 Git 的身份验证方法一样强大。 例如，如果 Git 需要多重身份验证，则 Fabric 也需要多重身份验证。
• 目前不支持连接到 Analysis Services 的 Power BI 数据集。
• 安装了模板应用的工作区无法连接到 Git。
• 不支持子模块。
• 目前不支持主权云。

Azure DevOps 限制

• Azure DevOps 帐户必须注册到使用 Fabric 工作区的同一用户。
• 如果工作区和 Git 存储库位于两个不同的地理区域，则租户管理员必须启用跨地区导出。
• 如果组织设置了条件访问，请确保 Power BI 服务设置了相同的条件，以便身份验证按预期运行。
• 提交的大小限制为 125 MB。

GitHub 限制

• GitHub 无法强制实施跨地区验证。
• 一次性提交的文件的总大小限制为 50 MB。 因此，如果有多个项要提交，有时可能需要将其拆分，进行单独提交。 有关提交文件的详细信息，请参阅故障排除指南。

GitHub Enterprise 限制

不支持某些 GitHub Enterprise 设置。 例如：

• IP 允许列表
• 专用网络
• 自定义域

工作区限制

• 只有工作区管理员可以管理与 Git 存储库的连接，例如连接、断开连接或添加分支。
  连接后，具有权限的任何人都可以在工作区中工作。
• 工作区文件夹结构不会反映在 Git 存储库中。 文件夹中的工作区项将导出到根目录。

分支和文件夹限制

• 分支名称的最大长度为 244 个字符。
• 文件名的完整路径的最大长度为 250 个字符。 过长的名称会失败。
• 文件大小上限为 25 MB。
• 使用 Git 集成部署报表/数据集后，无法从服务下载 .pbix 格式的报表/数据集。
• 如果项目的显示名称如下，Git 文件夹在类型之前使用逻辑 ID (Guid) 作为前缀：
  • 超过 256 个字符
  • 以 . 或空格结尾
  • 包含以下任意字符："/:<>\*?|

目录名称限制

• 连接到 Git 存储库的目录的名称具有以下命名限制：

  • 目录名称不能以空格或选项卡开头或结尾。
  • 目录名称不能包含以下任何字符：“/：<>\*？|

• 项目文件夹（包含项文件的文件夹）不能包含以下任何字符：“：<>\*？|。 如果将文件夹重命名为包含这些字符之一的内容，Git 无法连接或与工作区同步，并发生错误。

扩展延伸限制

• 扩展延伸需要权限表中列出的权限。
• 必须有可用容量可供此操作使用。
• 所有工作区和分支命名限制在扩展延伸到新工作区时适用。
• 扩展延伸时，会创建新工作区，并且不会复制原始工作区中的设置。 调整任何设置或定义，以确保新工作区符合组织策略。
• 新工作区中仅提供 Git 支持的项目。
• 相关分支列表仅显示你有权查看的分支和工作区。
• 必须启用 Git 集成。

同步和提交限制

• 一次只能向一个方向同步。 无法同时提交和更新。
• 不支持敏感度标签，可能会禁用导出具有敏感度标签的项。 若要在不带敏感度标签的情况下提交具有敏感度标签的项，请向管理员寻求帮助。
• 适用于受限项。 将忽略文件夹中不受支持的项。
• 不允许出现重复名称。 即使 Power BI 允许出现重复名称，更新、提交或撤消操作也会失败。
• 不支持 B2B。
• 冲突解决已在 Git 中部分完成。
• 在提交到 Git 的过程中，Fabric 服务将删除项文件夹中不属于项定义的文件。 不会删除不在项目文件夹中的不相关文件。
• 提交更改后，你可能会注意到未对项进行的一些意外更改。 这些更改在语义上是微不足道的，可能出于多种原因而发生。 例如：
  • 手动更改项定义文件。 这些更改是有效的，但可能与通过编辑器完成的更改不同。 例如，如果在 Git 中重命名语义模型列并将此更改导入工作区，则下次向语义模型提交更改时，bim 文件将注册为已更改，修改后的列将推送到 columns 数组的后面。 这是因为生成 bim 文件的 AS 引擎会将重命名的列推送到数组的末尾。 此更改不会影响项的操作方式。
  • 提交使用 CRLF 换行符的文件。 该服务使用 LF（行摘要）换行符。 如果在 Git 存储库中有带 CRLF 换行符的项文件，则从服务提交时，这些文件将更改为 LF。 例如，如果在桌面中打开报表，请保存 .pbip 项目并使用 CRLF 将其上传到 Git。
• 使用增强刷新 API 刷新语义模型会导致每次刷新后产生 Git 差异。

相关内容

• 了解 Git 集成过程
• 管理 Git 分支
• Git 集成的最佳做法