在 Dataform 中创建和运行工作流
本快速入门面向希望在 BigQuery 中管理数据转换的数据工程师和数据分析师。在本快速入门中,您将学习如何使用 Dataform 核心(一种基于 SQL 的框架,用于将原始数据转换为经过整理、测试和记录的数据资产)创建和运行 Dataform 工作流。借助 Dataform,您可以在中央代码库中开发数据建模流水线并对其进行版本控制,从而确保可靠性和可伸缩性。
本快速入门将引导您完成以下 Dataform 流程,以创建工作流并在 BigQuery 中高效运转该工作流:
准备工作
- 登录您的 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles.
所需的角色
如需获得执行本快速入门中的所有任务所需的权限,请让您的管理员为您授予以下 IAM 角色:
-
针对项目或代码库的 Dataform Admin (
roles/dataform.admin) -
项目或特定数据集的 BigQuery Data Editor (
roles/bigquery.dataEditor) 角色 -
项目的 BigQuery Job User (
roles/bigquery.jobUser) -
自定义服务账号的 Service Account User (
roles/iam.serviceAccountUser) 角色
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
授予必需的角色
如需在 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)
如需授予这些角色,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 IAM 页面。
点击授予访问权限。
在新的主账号字段中,输入您的自定义服务账号 ID。
在选择角色菜单中,使用添加其他角色为每个额外角色逐一选择以下角色:
- BigQuery Data Editor
- BigQuery Data Viewer
- BigQuery Job User
点击保存。
在 Google Cloud 控制台中,打开服务账号页面。
选择您的自定义服务账号。
前往具有访问权限的正文,然后点击授予访问权限。
在新的主账号字段中,输入您的默认 Dataform 服务代理 ID。
默认 Dataform 服务代理 ID 采用以下格式:
service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com将
PROJECT_NUMBER替换为您的Google Cloud 项目的数字 ID。您可以在Google Cloud 控制台信息中心找到 Google Cloud 项目 ID。如需了解详情,请参阅标识项目。在选择角色列表中,添加以下角色:
- Service Account User
- 服务账号令牌创建者
点击保存。
如需详细了解如何授予角色,请参阅向 Dataform 授予所需的访问权限。
创建 Dataform 仓库
Dataform 代码库是一种资源,表示包含 Dataform 项目代码的 Git 代码库,用于开发、版本控制和编排工作流。如需创建代码库,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击 创建制品库。
在创建仓库页面上,执行以下操作:
在代码库 ID 字段中,输入
quickstart-repository。在区域列表中,选择
europe-west4。在服务账号列表中,为代码库选择一个自定义服务账号。
在 actAs 权限检查部分,强制对代码库的用户操作执行权限检查。
点击创建。
点击前往代码库。
您已成功创建 Dataform 代码库。接下来,您可以创建并初始化开发工作区。
API
如需创建代码库,请使用 projects.locations.repositories.create 方法。
使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories - 查询参数:
repositoryId=REPOSITORY_ID
curl 命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"serviceAccount": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"}' \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"
替换以下内容:
LOCATION:您希望在其中创建代码库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:您要在其中创建 Dataform 代码库的Google Cloud 项目的唯一标识符。REPOSITORY_ID:新 Dataform 代码库的唯一标识符,例如quickstart-repository。SERVICE_ACCOUNT_NAME:为运行 BigQuery 作业而创建的自定义服务账号的 ID。
创建并初始化开发工作区
Dataform 工作区是一个隔离的开发环境(类似于 Git 分支),您可以在其中修改和编译代码。如需创建工作区,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository。点击 创建开发工作区。
在创建开发工作区窗口中,执行以下操作:
在工作区 ID 字段中,输入
quickstart-workspace。点击创建。
系统会显示开发工作区页面。
点击初始化工作区。
API
如需创建 Dataform 工作区,请使用
projects.locations.repositories.workspaces.create方法。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces - 查询参数:
workspaceId=WORKSPACE_ID
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d "{}" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces?workspaceId=WORKSPACE_ID"- 端点:
如需使用必要的配置初始化工作区,请创建一个名为
workflow_settings.yaml的本地文件,并粘贴以下配置:defaultProject: PROJECT_ID defaultDataset: dataform dataformCoreVersion: CORE_VERSION在终端中,运行以下命令,将文件内容编码为单个连续字符串:
base64 -w 0 workflow_settings.yaml复制生成的输出字符串,以在 JSON 请求正文的
SETTINGS_DEFINITION字段中使用。如需在工作区中创建配置文件,请使用
projects.locations.repositories.workspaces.writeFile方法。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "path": "workflow_settings.yaml", "contents": "SETTINGS_DEFINITION" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"替换以下内容:
CORE_VERSION:Dataform 核心的最新稳定(非 Beta)版本,例如3.0.43。您可以在版本中找到列出的最新版本。LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的Google Cloud 项目的唯一标识符。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。SETTINGS_DEFINITION:YAML 文件的内容(以 Base64 编码的字符串形式)。WORKSPACE_ID:Dataform 开发工作区的唯一标识符,例如feature-branch-1。
- 端点:
创建视图
Dataform 视图是在 SQLX 文件中定义的资源,可用于转换数据,并作为工作流中其他表或视图的来源。如需创建并定义一个稍后将用作表数据源的视图,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository,然后点击quickstart-workspace。在文件窗格中,点击
definitions/旁边的 更多菜单。点击创建文件。
在创建新文件窗格中,执行以下操作:
在添加文件路径字段中,输入
definitions/quickstart-source.sqlx。点击创建文件。
在文件窗格中,展开“定义”文件夹。
点击
definitions/quickstart-source.sqlx。在文件中输入以下代码段:
config { type: "view" } SELECT "apples" AS fruit, 2 AS count UNION ALL SELECT "oranges" AS fruit, 5 AS count UNION ALL SELECT "pears" AS fruit, 1 AS count UNION ALL SELECT "bananas" AS fruit, 0 AS count点击格式。
API
如需创建视图,您必须先准备好 SQLX 文件内容,以用于 API 请求。
创建名为
quickstart-source.sqlx的本地文件,并粘贴以下 SQL 代码段:config { type: "view" } SELECT "apples" AS fruit, 2 AS count UNION ALL SELECT "oranges" AS fruit, 5 AS count UNION ALL SELECT "pears" AS fruit, 1 AS count UNION ALL SELECT "bananas" AS fruit, 0 AS count在终端中,运行以下命令将文件内容编码为单个连续字符串:
base64 -w 0 quickstart-source.sqlx复制生成的输出字符串,以在 JSON 请求正文的
VIEW_DEFINITION字段中使用。如需在工作区中创建和定义视图定义文件,请使用
projects.locations.repositories.workspaces.writeFile方法。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
JSON 载荷 (
write_view.json):{ "path": "definitions/quickstart-source.sqlx", "contents": "VIEW_DEFINITION" }curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @write_view.json \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"替换以下内容:
LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的Google Cloud 项目的唯一标识符。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。VIEW_DEFINITION:SQLX 文件的内容(以 Base64 编码的字符串形式)。WORKSPACE_ID:Dataform 开发工作区的唯一标识符,例如feature-branch-1。
- 端点:
创建表
Dataform 表是在 SQLX 文件中定义的资源,用于将转换后的查询结果存储在 BigQuery 中,作为工作流的一部分。如需为工作流定义表格,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository,然后点击quickstart-workspace。在文件窗格中,点击
definitions/旁边的 更多菜单,然后选择创建文件。在添加文件路径字段中,输入
definitions/quickstart-table.sqlx。点击创建文件。
在文件窗格中,展开
definitions/目录。选择
quickstart-table.sqlx,然后输入以下表类型和SELECT语句:config { type: "table" } SELECT fruit, SUM(count) as count FROM ${ref("quickstart-source")} GROUP BY 1点击格式。
定义表类型后,Dataform 会抛出查询验证错误,因为 BigQuery 中尚不存在 quickstart-source。运行工作流后,此错误将被解决。
API
如需创建表,您必须先准备好 SQLX 文件内容,以用于 API 请求。
创建名为
quickstart-table.sqlx的本地文件,并粘贴以下 SQL 代码段:config { type: "table" } SELECT fruit, SUM(count) as count FROM ${ref("quickstart-source")} GROUP BY 1在终端中,运行以下命令将文件内容编码为单个连续字符串:
base64 -w 0 quickstart-table.sqlx复制生成的输出字符串,以在 JSON 请求正文的
TABLE_DEFINITION字段中使用。如需在工作区中定义表格,请使用
projects.locations.repositories.workspaces.writeFile方法。此单个 API 请求取代了手动创建 SQLX 文件以及定义表结构和依赖项的步骤。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
JSON 载荷 (
write_table.json):{ "path": "definitions/quickstart-table.sqlx", "contents": "TABLE_DEFINITION" }curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @write_table.json \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"替换以下内容:
LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的Google Cloud 项目的唯一标识符。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。TABLE_DEFINITION:SQLX 文件的内容(以 Base64 编码的字符串形式)。WORKSPACE_ID:Dataform 开发工作区的唯一标识符,例如feature-branch-1。
- 端点:
在 BigQuery 中运行工作流
如需运行工作流,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository,然后点击quickstart-workspace。点击开始执行。
点击所有操作。
点击开始执行。
在随即打开的对话框中,点击允许,以授予 BigQuery Pipelines 访问您 Google 账号的权限。
Dataform 使用默认代码库设置在名为
dataform的 BigQuery 数据集中创建工作流的内容。
您已成功创建 Dataform 工作流并在 BigQuery 中运行该工作流。
API
如需在 BigQuery 中运行工作流,请将 SQLX 文件编译为标准 SQL,然后触发调用。
如需根据您的工作区创建编译结果,请使用
projects.locations.repositories.compilationResults.create方法。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "workspace": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults"替换以下内容:
LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的Google Cloud 项目的唯一标识符。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。WORKSPACE_ID:Dataform 开发工作区的唯一标识符,例如feature-branch-1。
- 端点:
从响应中,记下
/compilationResults/COMPILATION_ID格式的编译结果 ID。如需触发工作流调用,请使用
projects.locations.repositories.workflowInvocations.create方法。提供您创建的汇编结果的 ID。使用以下信息运行 API 请求:
- 端点:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "compilationResult": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults/COMPILATION_ID" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations"替换以下内容:
COMPILATION_ID:编译结果的唯一标识符。LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的唯一 Google Cloud 项目 ID。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。
- 端点:
您已成功创建 Dataform 工作流并在 BigQuery 中运行该工作流。
在 Dataform 中查看执行日志
如需查看执行日志,请选择以下选项之一:
控制台
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository,然后点击quickstart-workspace。点击工作流执行日志。
如需查看执行详情,请点击最新的执行。
API
如需查看执行历史记录,请使用
projects.locations.repositories.workflowInvocations.list方法。使用以下信息运行 API 请求:
- 端点:
GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations - 查询参数:为确保最新执行的作业显示在结果顶部,请使用
?orderBy=create_time desc。
curl命令:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations?orderBy=create_time%20desc"替换以下内容:
LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的唯一 Google Cloud 项目 ID。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。
- 端点:
如需查看特定执行的详细日志和状态,请使用
projects.locations.repositories.workflowInvocations.query方法。使用以下信息运行 API 请求:
- 端点:
GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations/WORKFLOW_INVOCATION_ID:query
curl命令:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations/WORKFLOW_INVOCATION_ID:query"替换以下内容:
LOCATION:制品库的 Google Cloud 区域,例如europe-west4。PROJECT_ID:Dataform 代码库所在的唯一 Google Cloud 项目 ID。REPOSITORY_ID:Dataform 代码库的唯一标识符,例如quickstart-repository。WORKFLOW_INVOCATION_ID:特定工作流执行的唯一标识符。您可以从workflowInvocations.list请求的结果中或从workflowInvocations.create响应的name字段中获取此标识符。
- 端点:
清理
为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用,请按照以下步骤操作。
删除在 BigQuery 中创建的数据集
为避免 BigQuery 资产产生费用,请删除名为 dataform 的数据集。
在 Google Cloud 控制台中,前往 BigQuery 页面。
在探索器面板中,展开您的项目并选择
dataform。点击 操作菜单,然后选择删除。
在删除数据集对话框中,在字段中输入
delete,然后点击删除。
删除 Dataform 开发工作区
创建 Dataform 开发工作区不会产生任何费用,但如需删除开发工作区,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
点击
quickstart-repository。在开发工作区标签页中,点击
quickstart-workspace旁边的 更多菜单,然后选择删除。请点击删除来确认操作。
删除 Dataform 代码库
创建 Dataform 代码库不会产生任何费用,但如需删除代码库,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 BigQuery Dataform 页面。
在
quickstart-repository旁边,点击 更多菜单,然后选择删除。在删除代码库窗口中,输入代码库的名称以确认删除。
请点击删除来确认操作。
后续步骤
- 如需详细了解 Dataform,请参阅 Dataform 概览。
- 如需了解如何将远程代码库连接到 Dataform 代码库,请参阅连接到第三方 Git 代码库。
- 如需了解如何替换代码库的默认 Dataform 设置,请参阅配置 Dataform 工作流设置。
- 如需详细了解如何在 BigQuery 中管理数据集,请参阅管理数据集。
- 如需详细了解如何在 BigQuery 中管理表,请参阅管理表。