使用 BigQuery Studio Git 代码库管理代码

借助 BigQuery Studio Git 代码库，您可以直接在 BigQuery Studio 文件浏览器中对 SQL 脚本、笔记本和其他代码资产进行版本控制。您无需离开 Google Cloud 控制台，即可克隆远程 Git 代码库、管理分支和执行 Git 操作。

与传统代码库相比，此集成在左侧窗格中的用户根文件夹下提供了简化的基于文件夹的体验。您可以像处理标准文件和目录一样处理代码资产，同时保持与远程 Git 代码库的连接。

限制

• BigQuery Studio Git 代码库仅限于用户根文件夹上下文，供私人使用。请勿与其他用户共享这些代码库。虽然这些代码库显示在用户根文件夹（项目中的资产的虚拟表示）中，但从技术上讲，它们是在项目级创建的。
• 装载位置中的文件系统操作会消耗 Dataform 配额。
• 如果代码库包含大量文件、文件较大、分支较多或提交历史记录较深且复杂，则克隆时间会更长。克隆操作可能会超出操作超时时间，从而导致无法成功创建代码库。如需缩短具有深度提交历史记录的代码库的克隆时间，您可以创建浅克隆。如果需要，您稍后可以提取更多提交记录。
• 存储在 BigQuery Studio Git 代码库装载中的笔记本文件的大小不能超过 30 MB。如果文件大于 30 MB，请将其保存到 Colab 运行时在装载位置之外的本地存储空间。

• 如果您在装载点之外对 Git 代码库进行更改（例如，在左侧窗格中修改或重命名文件），这些更改最多可能需要 60 秒才能在笔记本运行时的装载点内显示。您可以通过将 CACHE_TTL_SECONDS 参数传递给构造函数来调整此时长：

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  将 NUMBER 替换为缓存保持有效的秒数。减小此值会提高同步频率，并更快地消耗 Dataform 配额。

准备工作

在 Google Cloud 项目中启用 Developer Connect API。

启用该 API

所需的角色

如需获得使用 BigQuery Studio Git 代码库管理代码所需的权限，请让管理员为您授予项目的 Developer Connect OAuth User (roles/developerconnect.oauthUser) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含使用 BigQuery Studio Git 代码库管理代码所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您也可以使用自定义角色或其他预定义角色来获取这些权限。

代码库的安全注意事项

由于 BigQuery 中的代码资产由 Dataform 提供支持，因此您应考虑对有权访问这些资产的用户产生的以下安全影响：

• 代码资源的公开范围由项目级 Dataform 权限控制。拥有 dataform.repositories.list 权限（包含在 BigQuery Job User、BigQuery Studio User 和 BigQuery User 等标准 BigQuery 角色中）的用户可以在 Google Cloud 项目的探索器面板中查看所有代码资产，无论这些资产是否由他们创建或与他们共享。如需限制公开范围，您可以创建不包含 dataform.repositories.list 权限的自定义角色。
• 与 Dataform 服务代理共享的任何 Secret 都可能被有权修改这些资源的用户访问。为确保凭据安全，请限制创建和编辑权限，仅向可信用户授予这些权限，并限制 Dataform 服务代理可访问的 Secret。如需了解详情，请参阅软件包安装期间的 Secret 访问权限。

如需了解详情，请参阅 Dataform 权限的安全注意事项。

针对 Developer Connect 权限的安全建议

BigQuery Studio Git 代码库使用 Developer Connect 连接到远程仓库。此外，预定义的 BigQuery 和 Dataform 角色包含 Developer Connect 权限。由于这些安全功能，我们建议您执行以下操作：

• 使用自定义角色强制执行职责分离：如果您的组织要求严格分离数据分析任务和源代码管理，请部署省略 Developer Connect 权限的自定义角色。BigQuery User (roles/bigquery.user) 和 BigQuery Studio User (roles/bigquery.studioUser) 等预定义角色包含 Developer Connect 权限，这些权限可让分配了这些角色的用户启动 OAuth 流程和代理 Git 流量。
• 使用 IAM 拒绝政策强制执行防护措施：应用组织级拒绝政策，以防止广泛的分析群组执行敏感操作。考虑拒绝 developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken 权限以防止令牌提取，并拒绝 developerconnect.googleapis.com/accountConnectors.gitProxyWrite 权限以防止对代码库进行意外写入访问。BigQuery Admin (roles/bigquery.admin) 和 BigQuery Studio Admin (roles/bigquery.studioAdmin) 等管理角色包含令牌访问者权限，可让主账号检索有效的明文第三方源代码管理 (SCM) 令牌，例如 GitHub 应用安装令牌。
• 隔离敏感 CI/CD 项目：将敏感 CI/CD 流水线（例如 Cloud Build 或 Vertex AI）保留在与一般数据分析环境分开的专用 Google Cloud 项目中。由于 Developer Connect 权限的作用域限定在项目级，因此共享的多租户项目中的 BigQuery 用户可以列出并使用该项目中的任何 Developer Connect 连接来代理 Git 请求，这可能会授予对为 CI/CD 或基础架构自动化配置的代码库的访问权限。
• 使用 IAM Conditions 限制资源访问权限：将 IAM Conditions 附加到角色绑定，以将 Developer Connect 权限限制为特定资源。您可以根据资源名称前缀限制访问权限，也可以将访问权限范围限定为特定 Connection 和 GitRepositoryLink 资源。这样可以确保用户只能与适用于其工作流的 Developer Connect 连接进行交互。
• 保护资源名称中的敏感元数据：请勿在代码库名称、分支名称或连接 ID 中嵌入敏感凭据、项目代号或机密信息。列出这些资源所需的权限（developerconnect.connections.list 和 developerconnect.accountConnectors.list）会授予标准 BigQuery 角色。任何拥有基本项目访问权限的人都可以枚举这些资源并发现敏感元数据。

创建 BigQuery Studio Git 代码库

创建 Git 代码库时，请考虑以下要求：

• 如果远程代码库未向公共互联网开放（例如，如果它位于防火墙后面），则将远程 Git 代码库连接到 Git 代码库可能会失败。在这种情况下，请将所需的 Dataform 出站流量 IP 地址范围添加到防火墙规则中，以允许连接到受保护的远程仓库。
• 如需创建连接到 dataform.restrictGitRemotes 组织政策中未列入许可名单的远程 Git 代码库的 Git 代码库，请先将该远程 Git 代码库添加到相应政策的 allowedValues 列表中，然后再创建 Git 代码库。如需了解详情，请参阅限制远程仓库。

如需创建 Git 代码库，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 在左侧窗格中，点击 folder 文件以打开文件浏览器。

   如果您没有看到左侧窗格，请点击 last_page 展开左侧窗格以打开该窗格。

3. 在用户根节点旁边，依次点击 more_vert 查看操作 > 创建 > Git 代码库。

4. 输入远程 Git 代码库的网址。

5. BigQuery Studio 会检测是否有现成的 Developer Connect 账号连接器。您可以采取以下做法：

   • 如果找到账号连接器，系统会预填充 Git 代码库的显示名称。您可以修改这些值。
   • 如果不存在账号连接器，请点击创建账号连接器以创建新的账号连接器。
   • 如果您不想使用 Developer Connect 账号连接器，请点击使用其他连接类型，以使用 HTTPS 或 SSH 进行连接。

6. 可选：如需创建提交记录有限的浅克隆代码库，请点击高级选项，然后选中浅克隆复选框。

   1. 在深度字段中，输入要在有限的提交记录中检索的提交次数。

7. 点击连接。

编辑文件

如需修改文件，请点击文件节点（例如 SQL 脚本或笔记本），在新编辑器标签页中打开该文件。

您所做的任何更改都会自动保存。

管理文件

您可以使用与每个项关联的操作菜单执行标准管理任务。如需访问这些选项，请点击任何目录或文件旁边的 more_vert 查看操作。

在目录级，您可以执行以下任务：

• 在代码库中创建：创建新的代码资源，包括 SQL 查询、笔记本、数据画布、数据准备、文件或子目录。
• 上传到代码库：将本地机器中的现有文件导入所选目录。
• 重命名：更改目录的名称。
• 移动：重新定位目录。您只能将目录移到同一 Git 代码库中的其他位置。如需了解详情，请参阅移动目录或文件。
• 删除：从本地工作区中永久移除目录及其所有内容。如需了解详情，请参阅删除目录或文件。

在文件级别，您可以执行以下任务：

• 打开或打开方式：在默认编辑器或特定应用（例如特定笔记本环境）中查看文件。
• 重命名：更改文件名。
• 复制：创建文件的副本。您只能将文件复制到同一 Git 代码库中的目录。如需了解详情，请参阅复制文件。
• 移动：将文件重新定位到同一 Git 代码库中的另一个目录。如需了解详情，请参阅移动目录或文件。
• 下载：将文件副本保存到本地计算机。
• 删除：从工作区中移除文件。如需了解详情，请参阅删除目录或文件。

移动目录或文件

如需在 BigQuery Studio Git 代码库中移动目录或文件，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 在左侧窗格中，点击 folder 文件以打开文件浏览器。

3. 根据您要移动的资源数量，执行以下操作之一：

   • 如需移动单个资源，请在文件浏览器中选择要移动的目录或文件，然后依次点击 more_vert 查看操作 > 移动。
   • 如需移动多个资源，请在文件夹视图中选中要移动的每个资源旁边的复选框，然后点击移动。

4. 在“移动资源”对话框中，选择同一 Git 代码库中的目标目录。您只能将资源移至同一 Git 代码库中的位置。

5. 点击移动。

复制文件

如需在 BigQuery Studio Git 代码库中复制文件，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 在左侧窗格中，点击 folder 文件以打开文件浏览器。

3. 选择要复制的文件。

4. 点击 more_vert 查看操作 > 复制。

5. 在“复制资源”对话框中，选择同一 Git 代码库中的目标目录。您只能将文件复制到同一 Git 代码库中的位置。

6. 点击复制。

删除目录或文件

如需删除 BigQuery Studio Git 代码库中的目录或文件，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 在左侧窗格中，点击 folder 文件以打开文件浏览器。

3. 根据您要删除的资源数量，执行以下操作之一：

   • 如需删除单个资源，请在文件浏览器中选择要删除的目录或文件，然后依次点击 more_vert 查看操作 > 删除。
   • 如需删除多个资源，请在文件夹视图中选中要删除的每个资源旁边的复选框，然后点击删除。

4. 在删除确认对话框中，点击删除。

提交并推送更改

如需将本地修改与远程仓库同步，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 在左侧窗格中，点击 fork_right 源代码控制以打开源代码控制面板。

3. 可选：将鼠标悬停在修改后的文件上，然后点击显示差异，以查看本地版本与上次提交的版本之间的逐行比较。

4. 在提交消息字段中，输入更改说明。

5. 点击提交。您的更改会保存到本地分支的 Git 历史记录中。

6. 点击推送至远程分支。您的更改会与远程仓库同步。

检出新分支

您可以管理本地分支，并根据现有的本地或远程跟踪分支创建新的本地分支。

在源代码控制面板的分支部分中，您可以看到已检出的本地分支。CURRENT 标签表示您的活跃分支，DEFAULT 标签表示代码库的默认分支。

如需签出新分支，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 打开源代码控制面板。

3. 在分支部分，点击分支旁边的 more_vert 操作 > 签出新分支。

4. 在源分支菜单中，选择要作为新分支基础的分支，例如 origin/main。

5. 在分支名称字段中，输入新分支的名称。

6. 点击检出分支。BigQuery Studio 会先检出来源分支。如果提供的分支名称表示新分支，则系统会根据该来源创建新分支。新分支会成为活跃分支，并且 Git 代码库的内容会自动更新，以反映检出分支的状态。

如需切换到现有分支，请执行以下操作：

1. 在源代码控制面板中，展开分支部分。
2. 在要切换到的分支旁边，依次点击 more_vert 操作 > 切换到 BRANCH_NAME。

查看提交历史记录

您可以查看活跃分支的提交历史记录。如果您的代码库是作为浅克隆创建的，则分支提交历史记录窗格会显示一个信息横幅，指明该代码库的提交历史记录有限。您可以通过提取更多提交记录来扩展本地历史记录。

如需查看提交历史记录，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 打开源代码控制面板。

3. 点击主要版本控制操作按钮旁边的 expander_arrow 下拉箭头，然后点击查看提交历史记录。

   分支提交历史记录窗格随即打开，其中显示了活跃分支的提交历史记录。

4. 可选：如需从远程仓库提取提交，请执行以下任一操作：

   • 在主要版本控制操作按钮旁边，点击 expander_arrow 下拉箭头，然后点击从远程提取。
   • 在分支提交历史记录窗格中，点击提取。

   对于浅克隆代码库，在提取（浅克隆）对话框的要提取的其他提交字段中，输入要从代码库历史记录中检索的其他提交的数量。

   如果您输入 0，则不会检索其他历史提交记录，但 BigQuery Studio 会执行标准提取来同步远程引用和元数据。

5. 点击提取。

   您可以根据需要重复提取，直到检索到所有提交。

删除 Git 代码库

删除 BigQuery Studio Git 代码库会从 BigQuery Studio 环境中移除该代码库及其所有内容。

如需删除 Git 代码库，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 使用以下方法之一删除代码库：

   • 如需从文件浏览器中删除代码库，请在左侧窗格中点击 folder 文件。在要删除的 Git 代码库旁边，依次点击 more_vert 查看操作 > 删除。
   • 如需从控制面板中删除代码库，请在源代码控制面板标题下，依次点击 more_vert 源代码控制选项 > 删除 REPOSITORY_NAME。

3. 在删除确认对话框中，点击删除。

访问 Git 代码库装载中的笔记本文件

从 BigQuery Studio Git 代码库中访问笔记本时，您可以将主机 Git 代码库装载到笔记本的运行时。装载是一种连接，可让您的远程 Git 代码库看起来像是笔记本运行时中的本地代码库。这样，您的笔记本就可以直接访问、读取和写入同一代码库中的其他文件和查询脚本。

装载 Git 代码库

如需装载 Git 代码库，请在笔记本中运行以下 Python 代码：

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

笔记本连接到装载后，会发生以下变化：

• 笔记本会话的当前工作目录会更新，以反映其在 Git 代码库中的相对路径。这可确保基于路径的文件访问自动运行。
• Git 代码库在笔记本运行时中的路径会添加到 Python 系统路径中，这样您就可以使用标准 Python 导入语句将查询脚本和文件从 Git 代码库直接加载到笔记本中。

管理装载和连接

使用以下控件管理工作区：

• 装载工作区：启动 Git 代码库的装载过程。装载是共享资源，因此如果同一 Colab 运行时上的多个笔记本使用同一 Git 代码库，它们会使用同一装载。
• 卸载工作区：停止 Git 代码库的装载过程。卸载工作区后，该 Colab 运行时上正在使用该工作区的所有笔记本都将无法使用该装载。
• 连接工作区：启动与当前笔记本会话的活跃装载的连接。连接后，笔记本的工作目录和系统路径会更新，以包含 Git 代码库，从而让您可以访问和导入文件。
• 断开工作区连接：结束当前笔记本会话的装载连接，并将其重置为默认状态。断开连接不会影响其他活跃笔记本会话的装载连接状态。如需结束会话连接，我们建议您使用断开工作区连接按钮。
• 修复：在装载或连接变得不可用时，将其恢复到正常状态。

初始化装载后，请参阅状态栏，了解装载的实时运行状况和活动路径。可能的健康状态包括已连接、已装载、已停止和运行状况不佳。

后续步骤

• 了解如何创建笔记本。
• 了解如何创建已保存的查询。
• 了解如何创建和管理代码库。
• 了解如何使用文件夹整理代码资产。