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

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

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

限制

  • BigQuery Studio Git 代码库仅限于用户根文件夹上下文，供私人使用。请勿与其他用户共享这些代码库。虽然这些代码库显示在用户根文件夹（项目中的资产的虚拟表示）中，但从技术上讲，它们是在项目级创建的。
  • 不支持将 Developer Connect 账号连接器与 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 Studio Git 代码库管理代码，您需要具备以下权限：

  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • developerconnect.operations.list
  • developerconnect.operations.get
  • developerconnect.locations.list
  • developerconnect.locations.get
  • developerconnect.users.startOAuth
  • developerconnect.users.finishOAuth
  • developerconnect.users.fetchAccessToken
  • developerconnect.users.getSelf
  • developerconnect.users.deleteSelf
  • developerconnect.accountConnectors.get
  • developerconnect.accountConnectors.list
  • developerconnect.accountConnectors.gitProxyUse
  • developerconnect.accountConnectors.httpProxyUse
  • developerconnect.accountConnectors.gitProxyRead
  • developerconnect.accountConnectors.gitProxyWrite
  • developerconnect.accountConnectors.httpProxyRead
  • developerconnect.accountConnectors.httpProxyWrite
  • developerconnect.accountConnectors.fetchUserRepositories

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

代码库的安全注意事项

由于 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 权限的安全注意事项。

创建 BigQuery Studio Git 代码库

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

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

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

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

    转到 BigQuery

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

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

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

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

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

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

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

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

  7. 点击连接。

编辑文件

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

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

管理文件

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

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

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

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

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

移动或复制文件和目录

您可以移动或复制文件和目录，但它们必须保留在同一 Git 代码库中。

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

    转到 BigQuery

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

  3. 找到要移动或复制的文件或目录。

  4. 依次点击 打开操作 > 移动或复制。

  5. 在随即显示的对话框中，选择同一 Git 代码库中的目标目录。

  6. 点击移动或复制。

提交并推送更改

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

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

    转到 BigQuery

  2. 在左侧窗格中，点击 Repository（代码库）。

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

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

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

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

检出新分支

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

在 Repository 标签页的 Branches 部分，您可以查看已签出的本地分支。CURRENT 标签表示您的活跃分支，DEFAULT 标签表示代码库的默认分支。

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

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

    转到 BigQuery

  2. 在左侧窗格中，点击 代码库。

  3. 展开分支部分。

  4. 点击分支旁边的 打开操作，然后点击检出新分支。

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

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

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

查看提交历史记录

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

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

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

    转到 BigQuery

  2. 在左侧窗格中，点击 Repository（代码库）。

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

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

  4. 可选：如需为浅克隆代码库提取其他提交，请在分支提交历史记录窗格中点击提取。

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

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

    2. 点击提取。

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

访问 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 代码库，从而让您可以访问和导入文件。
  • 断开工作区连接：结束当前笔记本会话的装载连接，并将其重置为默认状态。断开连接不会影响其他活跃笔记本会话的装载连接状态。如需结束会话连接，我们建议您使用断开工作区连接按钮。
  • 修复：在装载或连接变得不可用时，将其恢复到正常状态。

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

后续步骤