创建代码库

本文档可帮助您了解 Dataform 中的代码库概念以及如何创建新代码库。

Dataform 代码库简介

每个 Dataform 代码库都包含一组构成工作流的 SQLX 和 JavaScript 文件，以及 Dataform 配置文件和软件包。您可以在开发工作区中与代码库的内容互动。

Dataform 会在 Dataform 页面上按代码库 ID 的字母顺序显示您的代码库。您可以对这些数据进行排序和过滤。

• 如需查看代码库，请在 Google Cloud 控制台中前往 Dataform 页面。

  前往 Dataform

每个 Dataform 代码库都连接到默认的 Dataform 服务代理或自定义服务账号。您只能在创建代码库时选择自定义服务账号。 您稍后可以修改服务账号。

默认情况下，Dataform 使用根据您的项目编号生成的服务代理或服务账号，采用以下格式：

[e-mail]

Dataform 使用 Git 记录更改并管理文件版本。每个 Dataform 代码库都对应一个 Git 代码库。 创建 Dataform 代码库后，您可以将其连接到远程 GitHub、GitLab 或 Bitbucket 代码库。

在 Dataform 代码库中，Dataform 会存储代码库代码。在连接的代码库中，第三方代码库会存储代码库代码。Dataform 会与第三方代码库进行互动，以便您在 Dataform 开发工作区中修改和执行其内容。

Dataform 代码库页面包含以下组件：

“开发工作区”标签页

显示在代码库中创建的开发工作区。

“工作流执行日志”标签页

显示 Dataform 工作流执行日志。

“版本和时间安排”标签页

可用于检查、创建、修改和删除版本配置和工作流配置。

“设置”标签页

显示代码库的名称和位置。对于已连接到第三方 Git 代码库的代码库，系统会显示第三方代码库来源、默认分支名称和密钥令牌。显示用于将代码库连接到第三方 Git 代码库和修改 Git 连接的按钮。

“创建开发工作区”按钮

让您可以创建开发工作区。

创建并初始化开发工作区后，您可以修改工作流设置文件，以配置代码库的以下 Dataform 设置：

• 默认数据库（Google Cloud 项目 ID）。
• 默认架构（BigQuery 数据集 ID）。
• 默认 BigQuery 位置。
• 断言的默认架构（BigQuery 数据集 ID）。
• 仓库，必须设置为 bigquery。
• 在编译期间可供项目代码使用的用户定义变量。

重要提示： 在 Dataform 中创建的代码库不会显示在 BigQuery 代码库中。

如需详细了解 Dataform 仓库设置，请参阅 Dataform 核心参考文档中的 IProjectConfig。

代码库设置

创建 Dataform 代码库时，您需要设置以下代码库设置：

仓库 ID

相应代码库的唯一 ID。ID 只能包含数字、字母、连字符和下划线。

区域

用于存储代码库及其内容的 Dataform 区域。

此存储区域可以与处理区域不同，Dataform 会在处理区域中处理您的代码并存储执行输出。 默认情况下，处理区域设置为默认的 BigQuery 数据集区域。创建代码库后，您可以在工作流设置文件中修改处理区域。如需了解详情，请参阅配置 Dataform 工作流设置。

服务代理或服务账号

与代码库关联的 Dataform 服务代理或自定义服务账号。对于新代码库，您必须提供自定义服务账号。您可以选择与您的Google Cloud 项目关联的服务账号，也可以手动输入其他服务账号。

默认情况下，Dataform 使用根据您的项目编号生成的服务代理或服务账号，格式如下：

[e-mail]

您必须使用自定义服务账号才能在代码库中运行工作流，但默认的 Dataform 服务代理仍用于所有其他代码库操作。

严格的“以…身份行动”模式

启用额外的安全检查，要求服务账号具有 iam.serviceAccounts.actAs 权限。 对于新代码库，系统会强制实施严格 act-as 模式。对于现有代码库，我们建议使用自定义服务账号并启用严格的 act-as 模式，以确保权限模型更加安全且可预测。

加密

代码库的加密方法。您可以使用默认加密、唯一的客户管理的 Cloud KMS 加密密钥或默认的 Dataform CMEK 密钥。如需详细了解如何在 Dataform 中使用客户管理的加密密钥 (CMEK)，请参阅使用客户管理的加密密钥。

创建代码库后，您可以将其连接到 GitHub 或 GitLab。

重要提示： 如需创建连接到 dataform.restrictGitRemotes 政策中未列入许可名单的远程 Git 代码库的 Dataform 代码库，请先将该远程 Git 代码库添加到相应政策的 allowedValues 列表中，然后再创建新的 Dataform 代码库并将其连接到该远程代码库。如需了解详情，请参阅限制远程代码库。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. 如需对代码库使用 CMEK 加密，请启用 Dataform 代码库的 CMEK 加密。

重要提示： 在创建要连接到远程 Git 代码库的 Dataform 代码库之前，请检查您的组织或项目是否通过 dataform.restrictGitRemotes 组织政策限制了远程 Git 代码库。如果已设置该政策，请确保在创建 Dataform 代码库并将其连接到远程代码库之前，将远程代码库列入许可名单。如需了解详情，请参阅限制远程代码库

所需的角色

如需获得创建和删除代码库所需的权限，请让管理员向您授予代码库的以下 IAM 角色：

• Dataform Admin (roles/dataform.admin) - 项目
• Service Account User (roles/iam.serviceAccountUser) - 自定义服务账号

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

授予必需的角色

如需在 Dataform 代码库和 BigQuery 中运行工作流，您可以使用自定义服务账号或您的 Google 账号。

您的自定义服务账号必须具有以下必需角色：

• BigQuery Data Editor (roles/bigquery.dataEditor) 角色，用于 Dataform 需要同时具有读取和写入权限的项目或特定 BigQuery 数据集。这通常包括托管 Dataform 代码库的项目。
• Dataform 需要对项目或特定 BigQuery 数据集具有只读权限，因此您需要为这些项目或数据集授予 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色。
• BigQuery Job User (roles/bigquery.jobUser) 角色，该角色针对的是托管 Dataform 代码库的项目。

如需让 Dataform 使用您的自定义服务账号，默认 Dataform 服务代理必须对自定义服务账号资源拥有以下角色：

• Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
• Service Account User (roles/iam.serviceAccountUser)

如需授予这些角色，请按照以下步骤操作：

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

   转到 IAM

2. 点击授予访问权限。

3. 在新的主账号字段中，输入您的自定义服务账号 ID。

4. 在选择角色菜单中，使用添加其他角色为每个额外角色逐一选择以下角色：

   • BigQuery Data Editor
   • BigQuery Data Viewer
   • BigQuery Job User

5. 点击保存。

6. 在 Google Cloud 控制台中，打开服务账号页面。

   转到“服务账号”

7. 选择您的自定义服务账号。

8. 前往具有访问权限的正文，然后点击授予访问权限。

9. 在新的主账号字段中，输入您的默认 Dataform 服务代理 ID。

   默认 Dataform 服务代理 ID 采用以下格式：

   [e-mail]
   

   将 PROJECT_NUMBER 替换为您的Google Cloud 项目的数字 ID。您可以在Google Cloud 控制台信息中心找到 Google Cloud 项目 ID。如需了解详情，请参阅标识项目。

10. 在选择角色列表中，添加以下角色：

    • Service Account User
    • 服务账号令牌创建者

11. 点击保存。

如需详细了解如何授予角色，请参阅向 Dataform 授予所需的访问权限。

创建代码库

如需创建 Dataform 代码库，请按以下步骤操作：

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

   前往 Dataform

2. 点击创建代码库。

3. 在创建代码库页面上的代码库 ID 字段中，输入唯一 ID。

   ID 只能包含数字、字母、连字符和下划线。

4. 在区域下拉列表中，选择用于存储代码库及其内容的 Dataform 区域。选择离您所在位置最近的 Dataform 区域。

   如需查看可用的 Dataform 区域列表，请参阅位置。代码库区域不必与 BigQuery 数据集所在的位置一致。

   在 workflow_settings.yaml 文件中，您可以设置处理区域，Dataform 会在该区域处理您的代码并存储执行输出。处理区域必须与 BigQuery 数据集所在的位置一致，但不必与代码库区域一致。如需了解详情，请参阅配置 Dataform 工作流设置。

5. 在服务账号菜单中，为代码库选择一个自定义服务账号。

   重要提示： 创建代码库时，您无法选择默认的 Dataform 服务代理。您必须为代码库使用自定义服务账号。

   在该菜单中，您可以选择与您有权访问的Google Cloud 项目关联的自定义服务账号。自定义服务账号仅用于工作流执行。所有其他代码库操作均由默认的 Dataform 服务代理执行。

   1. 可选：如需选择未显示在菜单中的服务账号，请点击手动输入，然后输入服务账号 ID。

6. 在 actAs 权限检查部分，强制对用户在代码库中的操作执行权限检查。如需详细了解这些检查，请参阅使用严格 act-as 模式。

7. 为代码库配置所选的加密机制：

   注意： Dataform 代码库创建后，您无法更改该代码库的加密机制。如需了解详情，请参阅 Dataform CMEK 限制

   默认 CMEK 密钥

   Dataform 会显示使用默认 KMS 密钥复选框，并默认选中该复选框。

   • 如需使用默认 Dataform CMEK 密钥加密代码库，请保持选中使用默认 KMS 密钥 复选框。

   注意： 如果您选中使用默认 KMS 密钥复选框，但未为项目设置默认 Dataform CMEK 密钥，Dataform 会对代码库应用静态加密。 使用客户管理的加密密钥。

   唯一的 CMEK 密钥

   如需使用唯一的 CMEK 密钥加密代码库，请执行以下操作：

   1. 如果系统默认选中使用默认 KMS 密钥复选框，请取消选中该复选框。
   2. 在加密部分中，选择客户管理的加密密钥 (CMEK) 选项。
   3. 在选择客户管理的密钥下拉菜单中，选择一个唯一的 CMEK 密钥。

   静态加密

   • 如需使用默认加密，请在加密部分中选择 Google-managed encryption key 选项。

   注意： 如果为代码库所在区域设置了默认 Dataform CMEK 密钥，您必须使用 CMEK 加密。请勿选择 Google-managed encryption key 选项。如需了解详情，请参阅 Dataform CMEK 限制。

8. 点击创建，然后点击前往代码库。

修改服务账号

您必须将自定义服务账号与 Dataform 代码库相关联，才能执行工作流。所有其他代码库操作仍由默认的 Dataform 服务代理执行。

如需修改 Dataform 代码库的服务账号，请按以下步骤操作：

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

   前往 Dataform

2. 选择一个代码库，然后点击设置。

   注意： Dataform 代码库列表仅包含为 Dataform 工作流开发创建的代码库。 BigQuery Studio 资产（例如笔记本或已保存的查询）的代码库是单独管理的，不会显示在此列表中。

3. 在服务账号字段旁边，点击 修改服务账号。

4. 在服务账号菜单中，为代码库选择一个服务账号。

   在该菜单中，您可以选择与您有权访问的Google Cloud 项目关联的自定义服务账号。

   1. 可选：如需选择未显示在菜单中的服务账号，请点击手动输入，然后输入服务账号 ID。

5. 点击保存。

删除代码库

如需删除代码库及其所有内容，请按照以下步骤操作：

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

   前往 Dataform

2. 在要删除的代码库旁边，点击 更多菜单，然后选择删除。

3. 在删除代码库窗口中，输入代码库的名称以确认删除。

4. 点击删除。

后续步骤

• 如需了解如何将 Dataform 代码库连接到第三方 Git 代码库，请参阅连接到第三方 Git 代码库。
• 如需详细了解代码库大小对 Dataform 开发的影响，请参阅代码库大小概览。
• 如需详细了解如何在 Dataform 中拆分代码库，请参阅代码库拆分简介。
• 如需了解如何配置 Dataform 处理设置，请参阅配置 Dataform 工作流设置。
• 如需了解如何创建和初始化工作区，请参阅创建工作区。