连接 Git 代码库并运行工作流
本快速入门将引导您完成以下过程:创建 Dataform 代码库、将其连接到现有的第三方 Git 代码库,以及运行工作流。您可以使用Google Cloud 控制台和 Dataform API 执行以下任务:
- 创建 Dataform 仓库。
- 将代码库连接到
dataform-co/dataform-example-project-bigqueryGitHub 代码库。 - 创建并初始化开发工作区。
- 向项目添加新版视图。
- 编译项目并在 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, Dataform, and Secret Manager 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, Dataform, and Secret Manager 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) 角色
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
创建 Dataform 仓库
代码库是 Dataform 项目的主要容器。 从下列选项中选择一项:
控制台
前往 BigQuery Dataform 页面。
点击 创建制品库。
在创建仓库页面上,执行以下操作:
- 在代码库 ID 字段中,输入
quickstart-repo。 - 在区域列表中,选择一个区域,例如
europe-west4。 - 在服务账号列表中,为代码库选择一个自定义服务账号。
- 点击创建。
- 点击前往代码库。
- 在代码库 ID 字段中,输入
您已成功创建 Dataform 代码库。接下来,您可以将 Dataform 代码库连接到远程 Git 代码库。
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"
替换以下内容:
SERVICE_ACCOUNT_NAME:为运行 BigQuery 作业而创建的自定义服务账号的 ID。PROJECT_ID:您要在其中创建 Dataform 代码库的Google Cloud 项目的唯一标识符。LOCATION:您希望在其中创建代码库的 Google Cloud 区域,例如europe-west4。REPOSITORY_ID:新 Dataform 代码库的唯一标识符,例如quickstart-repo。
您已成功创建 Dataform 代码库。接下来,您可以将 Dataform 代码库连接到远程 Git 代码库。
连接到 Git 代码库
如需将 Dataform 代码库连接到项目,请选择以下选项之一:
控制台
前往 Secret Manager 页面。
点击 创建密钥。
在名称字段中,输入
dataform-git-token。在密文值字段中,输入您的 GitHub 个人访问令牌 (PAT)。
如需了解如何创建 PAT,请参阅管理个人访问令牌。
我们建议您根据组织的安全政策为令牌设置过期日期。
点击创建密钥。
在密钥详情页面上,点击权限标签页,然后点击授予访问权限。
在新的主账号字段中,输入您的 Dataform 服务代理:
service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com。将
PROJECT_NUMBER替换为您的Google Cloud 项目编号。如需详细了解如何查找项目编号,请参阅查找项目名称、编号和 ID。在选择角色字段中,选择 Secret Manager > Secret Manager Secret Accessor。
点击保存。
在 Google Cloud 控制台中,前往 Dataform 页面。
点击
quickstart-repo。在代码库页面上,依次点击设置> 与 Git 建立连接。
在关联到远程代码库窗格中,选择 HTTPS。
在远程 Git 代码库网址字段中,输入
https://github.com/dataform-co/dataform-example-project-bigquery.git。在默认远程分支名称字段中,输入
master。在 Secret 菜单中,选择
dataform-git-token。点击关联。
您已成功将 Dataform 代码库连接到远程 Git 代码库,并授予了必要的权限。接下来,您可以创建并初始化开发工作区。
API
如需存储 Git 个人访问令牌,请使用
projects.secrets.create方法在 Secret Manager 中创建一个 Secret。使用以下信息运行 API 请求:- 端点:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets - 查询参数:
secretId=dataform-git-token 正文:
{ "replication": { "automatic": {} } }
或者,在终端中运行以下
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "replication": { "automatic": {} } }' \ "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=dataform-git-token"- 端点:
为包含 GitHub 个人访问令牌 (PAT) 的 Secret 添加版本。如需了解如何创建 PAT,请参阅管理个人访问令牌。我们建议您根据组织的安全政策为令牌设置过期日期。
如需添加密文版本,请使用
projects.secrets.addVersion方法。使用以下信息运行 API 请求:- 端点:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/dataform-git-token:addVersion 正文:
{ "payload": { "data": "GITHUB_PAT" } }
或者,在终端中运行以下
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "payload": { "data": "$(echo -n "GITHUB_PAT" | base64)" } }' \ "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/dataform-git-token:addVersion"将
GITHUB_PAT替换为您的 GitHub 个人访问令牌。curl命令会在发送请求之前自动将您的 PAT 转换为 Base64 编码的字符串。- 端点:
如需允许 Dataform 访问该 Secret,请向 Dataform 服务代理授予 Secret Manager Secret Accessor 角色 (
roles/secretmanager.secretAccessor)。如需授予该角色,请选择以下选项之一:gcloud
运行
gcloud secrets add-iam-policy-binding命令:gcloud secrets add-iam-policy-binding dataform-git-token \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" \ --role="roles/secretmanager.secretAccessor"将
PROJECT_NUMBER替换为您的Google Cloud 项目编号。如需详细了解如何查找项目编号,请参阅查找项目名称、编号和 ID。Secret Manager API
使用
projects.secrets.setIamPolicy方法。 使用以下信息运行 API 请求:- 端点:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/dataform-git-token:setIamPolicy 正文:
{ "policy": { "bindings": [ { "role": "roles/secretmanager.secretAccessor", "members": [ "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" ] } ] } }
或者,在终端中运行以下
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "policy": { "bindings": [ { "role": "roles/secretmanager.secretAccessor", "members": [ "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" ] } ] } }' \ "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/dataform-git-token:setIamPolicy"将
PROJECT_NUMBER替换为您的Google Cloud 项目编号。如需详细了解如何查找项目编号,请参阅查找项目名称、编号和 ID。- 端点:
如需将代码库连接到远程 Git 代码库,请使用
projects.locations.repositories.patch方法。使用以下信息运行 API 请求:- 端点:
PATCH https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID - 查询参数:
updateMask=gitRemoteSettings
或者,在终端中运行以下
curl命令:curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "gitRemoteSettings": { "url": "https://github.com/dataform-co/dataform-example-project-bigquery.git", "defaultBranch": "master", "authenticationTokenSecretVersion": "projects/PROJECT_ID/secrets/dataform-git-token/versions/1" } }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID?updateMask=gitRemoteSettings"- 端点:
您已成功将 Dataform 代码库连接到远程 Git 代码库,并授予了必要的权限。接下来,您可以创建并初始化开发工作区。
创建并初始化开发工作区
工作区是一个隔离的开发环境。如需创建并初始化工作区,请选择以下选项之一:
控制台
前往 BigQuery Dataform 页面。
点击
quickstart-repo。在代码库中,前往开发工作区标签页。
点击 创建开发工作区。
在工作区 ID 字段中,输入
dev-workspace。点击创建。
在开发工作区标签页中,选择
dev-workspace工作区。
您已成功创建并初始化开发工作区。接下来,您可以配置工作流设置。
API
如需创建工作区,请使用 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"
将 WORKSPACE_ID 替换为新 Dataform 开发工作区的唯一标识符,例如 dev-workspace。
您已成功创建并初始化开发工作区。接下来,您可以配置工作流设置。
配置工作流设置
在本部分中,您将更新 workflow_settings.yaml 文件中的项目 ID,以确保 Dataform 在您的Google Cloud 项目中执行工作流。如需配置工作流设置,请选择以下选项之一:
控制台
前往 BigQuery Dataform 页面。
点击
quickstart-repo。在代码库中,前往开发工作区标签页,然后点击
dev-workspace。在文件窗格中,选择
workflow_settings.yaml。在该文件中,将
defaultProject的值替换为您的项目 ID。文件会自动保存。
您已成功更新工作流设置。接下来,您可以向项目中添加新的来源声明。
API
创建一个名为
workflow_settings.yaml的本地文件,并将以下配置粘贴到该文件中:defaultProject: PROJECT_ID defaultDataset: dataform dataformCoreVersion: CORE_VERSION将
CORE_VERSION替换为最新稳定版(非 Beta 版)的 Dataform 核心,例如3.0.43。您可以在版本中找到列出的最新版本。在终端中,将文件内容编码为 Base64 字符串:
base64 -w 0 workflow_settings.yaml复制生成的输出字符串,以便在您决定稍后在这些步骤中使用替代
curl命令时,将其用于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"将
SETTINGS_DEFINITION替换为 YAML 文件的内容(以 Base64 编码的字符串形式)。- 端点:
您已成功更新工作流设置。接下来,您可以向项目中添加新的来源声明。
创建来源
在此部分中,您将向项目中添加一个新的 SQLX 来源声明,用于定义现有的 BigQuery 数据集,以便 Dataform 可以在工作流中将其作为数据源进行引用。如需创建新来源,请选择以下选项之一:
控制台
前往 BigQuery Dataform 页面。
点击
quickstart-repo。在代码库中,前往开发工作区标签页,然后点击
dev-workspace。在文件窗格中,选择
definitions文件夹。依次点击 更多文件操作 > 创建文件。
在添加文件路径字段中,输入
definitions/sources/tags.sqlx。点击创建文件。
在新的
definitions/sources/tags.sqlx文件的 SQL 编辑器中,粘贴以下代码:config { type: "declaration", database: "bigquery-public-data", schema: "stackoverflow", name: "tags" }
您已成功创建来源声明。接下来,您可以向项目中添加新视图。
API
- 创建名为
tags.sqlx的本地文件。 将以下代码粘贴到
tags.sqlx文件中:config { type: "declaration", database: "bigquery-public-data", schema: "stackoverflow", name: "tags" }在终端中,将文件内容编码为单个连续字符串:
base64 -w 0 tags.sqlx复制生成的输出字符串,以便在您决定稍后在这些步骤中使用替代
curl命令时,将其用于SOURCE_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": "definitions/sources/tags.sqlx", "contents": "SOURCE_DEFINITION" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"将
SOURCE_DEFINITION替换为 SQLX 文件的内容(以 Base64 编码的字符串形式)。- 端点:
您已成功创建来源声明。接下来,您可以向项目中添加新视图。
创建视图
在本部分中,您将向项目中添加一个用于定义视图的新 SQLX 文件。 如需创建新版视图,请选择以下选项之一:
控制台
前往 BigQuery Dataform 页面。
点击
quickstart-repo。在代码库中,前往开发工作区标签页,然后点击
dev-workspace。在文件窗格中,选择
definitions文件夹。依次点击 更多文件操作 > 创建文件。
在添加文件路径字段中,输入
definitions/top_question_tags.sqlx。点击创建文件。
在新的
definitions/top_question_tags.sqlx文件的 SQL 编辑器中,粘贴以下代码:config { type: "view", name: "top_question_tags", tags: ["daily"], schema: "reporting", } select tag_name, count from ${ref("tags")} order by count desc limit 100
您已成功创建视图。接下来,您可以编译项目。
API
- 创建名为
top_question_tags.sqlx的本地文件。 将以下代码粘贴到
top_question_tags.sqlx文件中:config { type: "view", name: "top_question_tags", tags: ["daily"], schema: "reporting", } select tag_name, count from ${ref("tags")} order by count desc limit 100在终端中,将文件内容编码为单个连续字符串:
base64 -w 0 top_question_tags.sqlx复制生成的输出字符串,以便在您决定稍后在这些步骤中使用替代
curl命令时,将其用于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
或者,在终端中运行以下
curl命令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "path": "definitions/top_question_tags.sqlx", "contents": "VIEW_DEFINITION" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"将
VIEW_DEFINITION替换为 SQLX 文件的内容(以 Base64 编码的字符串形式)。- 端点:
您已成功创建视图。接下来,您可以编译项目。
编译项目
编译会将 SQLX 文件转换为纯 SQL 执行图。如需编译项目,请选择以下选项之一:
控制台
Google Cloud 控制台会自动编译您的项目。您可以在工作区的已编译的图标签页中验证编译结果。
您已成功编译项目并验证执行图。 接下来,您可以在 BigQuery 中执行工作流。
API
如需根据工作区创建编译结果,请使用
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"- 端点:
如需验证项目是否已成功编译,请使用
projects.locations.repositories.compilationResults.get方法。使用以下信息运行 API 请求:- 端点:
GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults/COMPILATION_ID
或者,在终端中运行以下
curl命令:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults/COMPILATION_ID"将
COMPILATION_ID替换为编译结果的唯一标识符。此 ID 在上一步中编译请求的响应中提供。- 端点:
在响应中,检查
compilationErrors字段。如果列表为空,则表示您的项目已成功编译。
您已成功编译项目并验证执行图。 接下来,您可以在 BigQuery 中执行工作流。
运行工作流
如需在 BigQuery 中触发工作流的执行,请选择以下选项之一:
控制台
前往 BigQuery Dataform 页面。
点击
quickstart-repo。在代码库中,前往开发工作区标签页,然后点击
dev-workspace。在工具栏中,依次点击开始执行 > 执行操作。
选择所有操作。
点击开始执行。
您已成功运行工作流。
API
如需触发工作流调用,请使用 projects.locations.repositories.workflowInvocations.create 方法。
使用以下信息运行 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"
您已成功运行工作流。
清理
为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用,请按照以下步骤操作。
删除 BigQuery 数据集
为避免 BigQuery 资产产生费用,请删除此工作流创建的数据集,例如名为 reporting 和 staging 的数据集。
在 Google Cloud 控制台中,前往 BigQuery 页面。
在浏览器面板中,展开您的项目并选择数据集。
点击 操作菜单,然后选择删除。
在删除数据集对话框中,在字段中输入
delete,然后点击删除。
删除 Secret Manager Secret
如需清理安全资源,请删除用于 Git 连接的 Secret。
在 Google Cloud 控制台中,前往 Secret Manager 页面。
选择
dataform-git-tokenSecret。点击删除。
在确认对话框中,输入密文名称以进行确认,然后点击删除。
删除 Dataform 开发工作区
创建 Dataform 开发工作区不会产生任何费用,但如需删除开发工作区,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 Dataform 页面。
点击
quickstart-repo。在开发工作区标签页中,点击
dev-workspace旁边的 更多菜单,然后选择删除。请点击删除来确认操作。
删除 Dataform 代码库
创建 Dataform 代码库不会产生任何费用,但如需删除代码库,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 Dataform 页面。
在
quickstart-repo旁边,点击 更多菜单,然后选择删除。在删除代码库窗口中,输入代码库的名称以确认删除。
请点击删除来确认操作。
后续步骤
- 如需了解如何在 Dataform 中声明数据源,请参阅声明数据源。
- 如需了解如何在 Dataform 中创建视图和表,请参阅创建表。
- 如需详细了解 Dataform 中的版本控制,请参阅对代码进行版本控制。
- 如需了解如何安排工作流运行,请参阅使用工作流配置安排运行。