创建代码库

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

Dataform 代码库简介

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

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

• 如需查看代码库，请在 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 服务代理仍用于所有其他代码库操作。

严格 act-as 模式

启用额外的安全检查，要求服务帐号具有 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 代码库的项目。
• BigQuery Data Viewer (roles/bigquery.dataViewer) ，针对 Dataform 需要具有只读权限的项目或特定 BigQuery 数据集。
• 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
    • Service Account Token Creator

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. 可选：如需选择菜单中未显示的服务帐号（例如，如果您缺少查看角色列表所需的 iam.serviceAccounts.list 权限），请点击手动输入 并输入服务帐号 ID。
   注意： iam.serviceAccounts.list 权限在 “查看服务账号”角色 (roles/iam.serviceAccountViewer) 中提供。

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 工作流设置。
• 如需了解如何创建和初始化工作区，请参阅 创建工作区。