使用 IAM 控制访问权限

本文档介绍了如何在 Dataform 中执行以下操作：

• 授予 Dataform 所需的访问权限。
• 使用 IAM 控制对 Dataform 的访问权限。
• 使用 IAM 控制对各个表的访问权限。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

向 Dataform 授予所需的访问权限

本部分介绍如何授予 Dataform 服务代理和自定义服务账号在 BigQuery 中运行工作流所需的 Identity and Access Management (IAM) 角色。

自定义服务账号和 Dataform 服务代理简介

您可以按以下方式配置自定义服务账号，以代表您运行工作流：

• 在代码库级别，运行给定代码库中的所有工作流。
• 针对每个工作流配置单独设置。

创建 Dataform 代码库或工作流配置时，您可以选择您拥有 act-as 权限的任何服务账号。您必须为与 Dataform 资源关联的所有服务账号配置所需权限。

重要提示： 我们建议您启用严格的 act-as 模式，因为这有助于为您的 Dataform 项目确保更安全、更可预测的权限模型。

创建第一个 Dataform 代码库时，Dataform 会自动生成默认服务代理。 Dataform 使用默认服务代理代表您与 BigQuery 进行交互。

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

[e-mail]

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

Dataform 服务代理、自定义服务账号和 Google 账号所需的角色

用于在 Dataform 中进行身份验证的默认 Dataform 服务代理、自定义服务账号和 Google 账号用户凭据（预览版）需要以下 BigQuery IAM 角色，才能在 BigQuery 中运行工作流：

• Dataform 需要对项目拥有读取和写入权限，因此您需要向 Dataform 授予这些项目的 BigQuery Data Editor 角色。 这些项目通常包括托管 Dataform 代码库的项目。
• Dataform 需要对项目拥有只读权限，因此请向这些项目授予 BigQuery Data Viewer 角色。
• 托管 Dataform 代码库的项目中的 BigQuery Job User 角色。
• BigQuery Data Owner（如果您想查询 BigQuery 数据集）。
• 如果您想使用 BigQuery 政策标记，请参阅用于列级访问权限控制的 BigQuery 角色。

此外，请在工作流配置的有效服务账号上向默认 Dataform 服务代理授予以下角色：

• Service Account User (roles/iam.serviceAccountUser)
• Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
注意： 如果您向默认 Dataform 服务代理授予 Service Account Token Creator 角色，使其能够访问项目中的自定义服务账号，则可以在任何 Dataform 代码库中使用该自定义服务账号。这意味着，任何可以在 Dataform 中运行工作流的用户都可以使用项目中的此服务账号。为降低这种风险，我们建议您启用严格的“以…身份行动”模式（预览版）。

对于自动代码库发布和自动工作流运行，请向默认 Dataform 服务代理授予有效服务账号的 iam.serviceAccounts.actAs 权限。

安全注意事项

向 Dataform 服务代理、自定义服务账号或用户的 Google 账号授予 Dataform 所需的角色（预览版）时，需要考虑以下安全问题：

• 无论 VPC Service Controls 如何，任何被授予所需角色的服务代理或服务账号都可能会获得对相应服务代理或服务账号所属项目中的 BigQuery 或 Secret Manager 的访问权限。 源自 Dataform 的请求（使用具有所需角色的服务代理）位于 Dataform 代码库所属项目的 VPC Service Controls 边界内。

  如需了解详情，请参阅配置 VPC Service Controls。

• 拥有 dataform.repositories.create IAM 权限的任何用户都可以使用默认 Dataform 服务代理和授予该服务代理或服务账号的所有权限来运行代码。

  如需了解详情，请参阅 Dataform 权限的安全注意事项。

如需限制用户、服务代理或服务账号在 BigQuery 中可以读取或写入的数据，您可以向所选 BigQuery 数据集或表授予精细的 BigQuery IAM 权限。如需了解详情，请参阅控制对数据集的访问权限和控制对表和视图的访问权限。

为防止用户在使用其他用户的 Google 账号用户凭据时执行操作，系统会强制执行以下限制：

• 如需修改附加了其他 Google 账号用户凭据的工作流配置，您需要将自己的 Google 账号用户凭据附加到该工作流配置，或者更改该工作流配置以使用 {dataform_name_short} 服务代理或自定义服务账号进行身份验证。
• 如果存在引用发布配置且附加了其他 Google 账号用户凭据的工作流配置，您就无法修改发布配置的编译结果。

• 您无法将工作流配置设置为使用 Google 账号用户凭据进行身份验证，并引用具有时间表的发布配置。此限制会带来以下后果：

  • 如果工作流配置引用了设置为使用 Google 账号用户凭据进行身份验证的版本配置，则您无法更新该版本配置以使用时间表。
  • 您无法创建使用 Google 账号用户凭据进行身份验证并指向具有时间表的发布配置的工作流配置。
  • 您无法创建或更新工作流配置，以使用 Google 账号用户凭据并指向具有时间表的发布配置。

授予所需的 BigQuery 角色

如需向默认 Dataform 服务代理、您要在 Dataform 中使用的自定义服务账号，或您要在 Dataform 中用于身份验证的用户 Google 账号（预览版）授予所需的 BigQuery IAM 角色，请按以下步骤操作：

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

   前往 Dataform

2. 选择或创建代码库。

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

   转到 IAM

4. 点击授予访问权限。

5. 在新的主账号字段中，输入服务代理 ID、服务账号 ID 或用户的 Google 账号电子邮件地址（预览版）。

6. 在选择角色列表中，选择 BigQuery Job User 角色。

7. 点击添加其他角色，然后在选择角色列表中选择 BigQuery Data Editor 角色。

8. 点击添加其他角色，然后在选择角色列表中选择 BigQuery Data Viewer 角色。

9. 点击保存。

授予自动工作流所需的角色

如需在 Dataform 中使用自定义服务账号，默认 Dataform 服务代理必须能够访问该自定义服务账号。这样，Dataform 就可以使用自定义服务账号上定义的权限来运行工作流，而不是使用默认服务代理的账号。

如需授予此访问权限，您需要向默认 Dataform 服务代理授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)，使其成为主账号。这样一来，默认 Dataform 服务代理便可通过创建短期有效凭据（称为令牌）来模拟服务账号。Dataform 需要使用这些令牌才能以自定义服务账号的身份运行工作流。

您还需要向默认 Dataform 服务代理授予 Service Account User 角色 (roles/iam.serviceAccountUser)。这样一来，默认 Dataform 服务代理就可以为由自定义服务账号运行的工作流配置启动新的自动工作流运行。

如需向默认 Dataform 服务代理授予对自定义服务账号的访问权限，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，依次前往 IAM > 服务账号。

   转到“服务账号”

2. 选择一个项目。

3. 在项目“PROJECT_NAME”的服务账号页面上，选择您的自定义服务账号。

4. 前往具有访问权限的主账号，然后点击授予访问权限。

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

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

   [e-mail]
   

6. 在选择角色列表中，选择 Service Account Token Creator 角色和 Service Account User 角色。

7. 点击保存。

现在，您可以在 Dataform 代码库中配置自定义服务账号了。

审核服务账号配置

本部分介绍如何审核 Dataform 资源，以确保服务账号使用情况和权限授予情况正确无误。使用自定义服务账号时，审核尤为重要，因为它们需要特定权限才能让默认 Dataform 服务代理运行。

为 Dataform 代码库或工作流配置使用自定义服务账号时，您必须验证默认 Dataform 服务代理是否对该自定义服务账号拥有 Service Account User 角色 (roles/iam.serviceAccountUser)。此角色授予 iam.serviceAccounts.actAs 权限，该权限允许由默认 Dataform 服务代理启动的预定运行模拟自定义服务账号。此外，请验证默认 Dataform 服务代理是否具有有效服务账号的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

验证代码库服务账号

首先，确定属于 Dataform 自身调度和执行范围的 dataform.Repository 资产。然后，验证这些纳入范围的代码库的服务账号配置。

1. 使用 Cloud Asset Inventory 列出所有 dataform.Repository 类型的资源。 如需了解详情，请参阅查看资产。

2. 对于 Cloud Asset Inventory 输出中的每个代码库，请检查 resource.data.labels 字段以确定其是否在范围内。确切路径可能会因导出格式而略有不同。

3. 通过检查标签映射中的 single-file-asset-type 键来识别范围外的代码库。如果存在此键，则表示相应代码库被 BigQuery 功能使用。如果值为 sql 或 data_canvas，则可以将相应代码库从服务账号权限检查中排除。

   缺少此密钥或这些值的其余代码库在服务账号权限检查范围内。

4. 对于每个纳入范围的代码库，请检查 Cloud Asset Inventory 输出中的 resource.data.serviceAccount 字段，以确定是否配置了自定义服务账号：

   • 如果存在 resource.data.serviceAccount 字段，且其值与项目的默认 Dataform 服务代理电子邮件地址不同，则表示相应代码库使用自定义服务账号。

   • 如果 resource.data.serviceAccount 字段不存在，或者该字段的值与项目的默认 Dataform 服务代理匹配，则代码库会使用默认服务代理。

     注意： 如果您希望配置自定义服务账号，但 resource.data.serviceAccount 字段缺失，请先在 Google Cloud 控制台中仔细检查代码库的配置。如果服务账号已在代码库中配置，但未显示在 Cloud Asset Inventory 输出中，请与 Cloud Customer Care 联系。

5. 如果使用自定义服务账号，请验证默认 Dataform 服务代理是否对该自定义服务账号同时拥有 Service Account User 角色 (roles/iam.serviceAccountUser) 和 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

验证工作流配置服务账号

为 Dataform 工作流配置使用专用自定义服务账号是一种安全最佳实践，符合最小权限原则。

如需验证 dataform.WorkflowConfig resources 的服务账号使用情况，请执行以下操作：

1. 使用 Cloud Asset Inventory 列出所有 dataform.WorkflowConfig 类型的资源。

2. 对于每项工作流配置，请检查 Cloud Asset Inventory 输出，以确定有效的服务账号：

   • 如果存在 resource.data.serviceAccount 字段，则此值为工作流配置中明确设置的服务账号的电子邮件地址。
   • 如果缺少 resource.data.serviceAccount 字段，工作流配置会从其父级代码库继承服务账号。检查父代码库的配置，找到有效的服务账号。

3. 通过比较有效服务账号的电子邮件地址与项目的默认 Dataform 服务代理的电子邮件地址，确定是否正在使用自定义服务账号。如果它们不同，则表示正在使用自定义服务账号。

4. 如果使用的是自定义服务账号，请确保默认 Dataform 服务代理已被授予该自定义服务账号的 Service Account User 角色 (roles/iam.serviceAccountUser) 和 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。借助这些权限，默认 Dataform 服务代理可以模拟自定义服务账号来启动工作流执行。

使用 IAM 控制对 Dataform 的访问权限

本部分介绍了 Dataform 的访问权限控制选项，并说明了如何查看和授予 Dataform 角色。Dataform 使用 Identity and Access Management (IAM) 进行访问权限控制。如需详细了解 IAM 中的角色和权限，请参阅 IAM 角色和权限索引。

预定义的 Dataform 角色

下表列出了可让您访问 Dataform 资源的预定义角色：

Role	Permissions
Dataform Admin (roles/dataform.admin) Full access to all Dataform resources.	dataform.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.config.get dataform.config.update dataform.folders.addContents dataform.folders.create dataform.folders.delete dataform.folders.get dataform.folders.getIamPolicy dataform.folders.move dataform.folders.queryContents dataform.folders.setIamPolicy dataform.folders.update dataform.locations.get dataform.locations.list dataform.operations.cancel dataform.operations.delete dataform.operations.get dataform.operations.list dataform.releaseConfigs.create dataform.releaseConfigs.delete dataform.releaseConfigs.get dataform.releaseConfigs.list dataform.releaseConfigs.update dataform.repositories.commit dataform.repositories.computeAccessTokenStatus dataform.repositories.create dataform.repositories.delete dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.move dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.repositories.scheduleRelease dataform.repositories.scheduleWorkflow dataform.repositories.setIamPolicy dataform.repositories.update dataform.teamFolders.create dataform.teamFolders.delete dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.teamFolders.setIamPolicy dataform.teamFolders.update dataform.workflowConfigs.create dataform.workflowConfigs.delete dataform.workflowConfigs.get dataform.workflowConfigs.list dataform.workflowConfigs.update dataform.workflowInvocations.cancel dataform.workflowInvocations.create dataform.workflowInvocations.delete dataform.workflowInvocations.get dataform.workflowInvocations.list dataform.workflowInvocations.query dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.setIamPolicy dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Code Commenter ^Beta (roles/dataform.codeCommenter) Permissions to comment, at the repository level. Grants CRUD access over commentThread and comment resources.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.folders.get dataform.folders.queryContents dataform.locations.get dataform.repositories.get dataform.repositories.readFile resourcemanager.projects.get resourcemanager.projects.list
Code Creator (roles/dataform.codeCreator) Access only to private and shared code resources. The permissions in the Code Creator let you create and list code in Dataform, and access only the code that you created and code that was explicitly shared with you.	dataform.commentThreads.get dataform.commentThreads.list dataform.comments.get dataform.comments.list dataform.folders.create dataform.locations.* dataform.locations.get dataform.locations.list dataform.repositories.create dataform.repositories.list resourcemanager.projects.get resourcemanager.projects.list
Code Editor (roles/dataform.codeEditor) Edit access code resources.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.addContents dataform.folders.create dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.repositories.commit dataform.repositories.computeAccessTokenStatus dataform.repositories.create dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Code Owner (roles/dataform.codeOwner) Full access to code resources.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.* dataform.folders.addContents dataform.folders.create dataform.folders.delete dataform.folders.get dataform.folders.getIamPolicy dataform.folders.move dataform.folders.queryContents dataform.folders.setIamPolicy dataform.folders.update dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.operations.list dataform.repositories.commit dataform.repositories.computeAccessTokenStatus dataform.repositories.create dataform.repositories.delete dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.move dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.repositories.setIamPolicy dataform.repositories.update dataform.workspaces.* dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.setIamPolicy dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Code Scheduler ^Beta (roles/dataform.codeScheduler) Access for scheduling workflows and releases.	dataform.releaseConfigs.create dataform.workflowConfigs.create
Code Viewer (roles/dataform.codeViewer) Read-only access to all code resources.	dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.repositories.computeAccessTokenStatus dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.list dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.searchFiles resourcemanager.projects.get resourcemanager.projects.list
Dataform Editor (roles/dataform.editor) Edit access to Workspaces and Read-only access to Repositories.	dataform.commentThreads.get dataform.commentThreads.list dataform.comments.get dataform.comments.list dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.config.get dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.operations.list dataform.releaseConfigs.get dataform.releaseConfigs.list dataform.repositories.computeAccessTokenStatus dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.workflowConfigs.get dataform.workflowConfigs.list dataform.workflowInvocations.* dataform.workflowInvocations.cancel dataform.workflowInvocations.create dataform.workflowInvocations.delete dataform.workflowInvocations.get dataform.workflowInvocations.list dataform.workflowInvocations.query dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Dataform Service Agent (roles/dataform.serviceAgent) Gives permission for the Dataform API to access a secret from Secret Manager Warning: Do not grant service agent roles to any principals except service agents.	dataform.compilationResults.create dataform.workflowInvocations.create resourcemanager.projects.get resourcemanager.projects.list
Team Folder Commenter ^Beta (roles/dataform.teamFolderCommenter) View and comment access to a team folder and its contents.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.repositories.computeAccessTokenStatus dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.list dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.searchFiles resourcemanager.projects.get resourcemanager.projects.list
Team Folder Contributor ^Beta (roles/dataform.teamFolderContributor) Edit access to a team folder and its contents.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.addContents dataform.folders.create dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.repositories.commit dataform.repositories.computeAccessTokenStatus dataform.repositories.create dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.teamFolders.update dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Team Folder Creator ^Beta (roles/dataform.teamFolderCreator) Access to create new team folders.	dataform.teamFolders.create
Team Folder Owner ^Beta (roles/dataform.teamFolderOwner) Full access to a team folder and its contents. Can share the team folder and its contents.	dataform.commentThreads.* dataform.commentThreads.create dataform.commentThreads.delete dataform.commentThreads.get dataform.commentThreads.list dataform.commentThreads.update dataform.comments.* dataform.comments.create dataform.comments.delete dataform.comments.get dataform.comments.list dataform.comments.update dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.* dataform.folders.addContents dataform.folders.create dataform.folders.delete dataform.folders.get dataform.folders.getIamPolicy dataform.folders.move dataform.folders.queryContents dataform.folders.setIamPolicy dataform.folders.update dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.operations.list dataform.repositories.commit dataform.repositories.computeAccessTokenStatus dataform.repositories.create dataform.repositories.delete dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.move dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.repositories.setIamPolicy dataform.repositories.update dataform.teamFolders.delete dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.teamFolders.setIamPolicy dataform.teamFolders.update dataform.workspaces.* dataform.workspaces.commit dataform.workspaces.create dataform.workspaces.delete dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.installNpmPackages dataform.workspaces.list dataform.workspaces.makeDirectory dataform.workspaces.moveDirectory dataform.workspaces.moveFile dataform.workspaces.pull dataform.workspaces.push dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.removeDirectory dataform.workspaces.removeFile dataform.workspaces.reset dataform.workspaces.searchFiles dataform.workspaces.setIamPolicy dataform.workspaces.writeFile resourcemanager.projects.get resourcemanager.projects.list
Team Folder Viewer ^Beta (roles/dataform.teamFolderViewer) View access to a team folder and its contents.	dataform.compilationResults.* dataform.compilationResults.create dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.repositories.computeAccessTokenStatus dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.list dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.searchFiles resourcemanager.projects.get resourcemanager.projects.list
Dataform Viewer (roles/dataform.viewer) Read-only access to all Dataform resources.	dataform.commentThreads.get dataform.commentThreads.list dataform.comments.get dataform.comments.list dataform.compilationResults.get dataform.compilationResults.list dataform.compilationResults.query dataform.config.get dataform.folders.get dataform.folders.getIamPolicy dataform.folders.queryContents dataform.locations.* dataform.locations.get dataform.locations.list dataform.operations.get dataform.operations.list dataform.releaseConfigs.get dataform.releaseConfigs.list dataform.repositories.computeAccessTokenStatus dataform.repositories.fetchHistory dataform.repositories.fetchRemoteBranches dataform.repositories.get dataform.repositories.getIamPolicy dataform.repositories.list dataform.repositories.queryDirectoryContents dataform.repositories.readFile dataform.teamFolders.get dataform.teamFolders.getIamPolicy dataform.workflowConfigs.get dataform.workflowConfigs.list dataform.workflowInvocations.get dataform.workflowInvocations.list dataform.workflowInvocations.query dataform.workspaces.fetchFileDiff dataform.workspaces.fetchFileGitStatuses dataform.workspaces.fetchGitAheadBehind dataform.workspaces.get dataform.workspaces.getIamPolicy dataform.workspaces.list dataform.workspaces.queryDirectoryContents dataform.workspaces.readFile dataform.workspaces.searchFiles resourcemanager.projects.get resourcemanager.projects.list

自定义 Dataform 角色

自定义角色可以包含您指定的任何权限。您可以创建包含执行特定管理操作权限的自定义角色，例如创建开发工作区或在开发工作区内创建文件和目录。如需创建自定义角色，请参阅创建和管理自定义角色。

Dataform 权限的安全注意事项

拥有 dataform.repositories.create 权限的任何用户都可以使用默认的 Dataform 服务代理和授予该服务代理的所有权限在 BigQuery 中运行代码。这包括执行 Dataform 工作流。

以下 IAM 角色包含 dataform.repositories.create 权限：

• BigQuery Admin (roles/bigquery.admin)
• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Studio User (roles/bigquery.studioUser)
• BigQuery User (roles/bigquery.user)
• Code Creator (roles/dataform.codeCreator)
• Code Editor (roles/dataform.codeEditor)
• Code Owner (roles/dataform.codeOwner)
• Colab Enterprise User (roles/aiplatform.colabEnterpriseUser)
• Dataform Admin (roles/dataform.admin)

如需限制用户、服务代理或服务账号在 BigQuery 中可以读取或写入的数据，您可以向所选 BigQuery 数据集或表授予精细的 BigQuery IAM 权限。如需了解详情，请参阅控制对数据集的访问权限和控制对表和视图的访问权限。

如需详细了解默认 Dataform 服务代理及其所需的角色和权限，请参阅授予 Dataform 所需的访问权限。

查看 Dataform 角色

在 Google Cloud 控制台中，执行以下步骤：

1. 前往 IAM 和管理 > 角色页面。

   打开“角色”

2. 在过滤条件字段中，选择使用范围，输入 Dataform，然后按 Enter 键。

3. 点击其中一个列出的角色，即可在右侧窗格中查看该角色的权限。

   例如，Dataform Admin 角色拥有对所有 Dataform 资源的完整访问权限。

如需详细了解如何授予项目的角色，请参阅授予角色。 您可以通过这种方式授予预定义角色或自定义角色。

控制对单个代码库的访问权限

如需使用精细的权限控制对 Dataform 的访问权限，您可以使用 Dataform API repositories.setIamPolicy 请求在各个代码库中设置 Dataform IAM 角色。

如需在单个 Dataform 代码库上设置 Dataform IAM 角色，请按以下步骤操作：

1. 在终端中，传递包含访问政策的 Dataform API repositories.setIamPolicy 请求。

2. 在政策中，将用户、群组、网域、服务代理或服务账号与所选角色绑定，格式如下：

   {
   "policy":
      {
         "bindings": [
         {
            "role": "roles/ROLE",
            "members": [
               "TYPE:IDENTIFIER",
            ]
         },
         ],
      }
   }
   

   替换以下内容：

   • ROLE：您要向制品库授予的 Dataform IAM 角色。
   • TYPE：user、group、domain 或 serviceAccount。
   • IDENTIFIER：您要向其授予角色的用户、群组、网域或服务账号。

3. 在 IAM 页面中，确保所有用户都可以通过具有 dataform.repositories.list 权限的 Dataform 角色查看 Dataform 代码库的完整列表。

4. 在 IAM 中，确保仅向需要对所有 Dataform 代码库拥有完整访问权限的用户授予所有代码库的 Dataform Admin 角色。

以下命令传递了 repositories.setIamPolicy Dataform API 请求，该请求会向单个用户授予对 sales 代码库的 Dataform 编辑器角色：

curl -H "Content-Type: application/json" -X POST -d '{ "policy": { "bindings": [{ "role": "roles/dataform.editor", "members": ["user:[e-mail]"]}] }}' "https://dataform.googleapis.com/v1/projects/examplepetstore/locations/us-central1/repositories/sales:setIamPolicy"

授予对代码库的公开访问权限

您可以通过向 allAuthenticatedUsers 主账号授予对 Dataform 代码库的 IAM 角色，来授予对该代码库的公开访问权限。

当您向 allAuthenticatedUsers 主账号分配 IAM 角色时，服务代理、服务账号和互联网上所有已使用 Google 账号进行身份验证的用户都会获得该角色。此标识符包括未关联到 Google Workspace 账号或 Cloud Identity 网域的账号，如个人 Gmail 账号。不包括未经身份验证的用户，例如匿名访问者。如需了解详情，请参阅所有经过身份验证的用户。

例如，如果您向 sales 代码库授予 allAuthenticatedUsers 的 Dataform Viewer 角色，那么互联网上所有已使用 Google 账号进行身份验证的服务代理、服务账号和用户都将拥有对所有 sales 代码资源的只读访问权限。

注意： 向 allAuthenticatedUsers 授予管理员、修改或执行级别权限可能会让不法分子访问您的数据并运行代码。仅授予所需的最低权限。

如需向公众授予对 Dataform 代码库的访问权限，请按以下步骤操作：

1. 在终端中，传递包含访问政策的 Dataform API repositories.setIamPolicy 请求。

2. 在政策中，按以下格式将 allAuthenticatedUsers 主账号绑定到所选角色：

   {
   "policy":
      {
         "bindings": [
         {
            "role": "roles/ROLE",
            "members": [
               "allAuthenticatedUsers",
            ]
         },
         ],
      }
   }
   

   将 ROLE 替换为您要向所有经过身份验证的用户授予的 Dataform IAM 角色。

以下命令会传递 repositories.setIamPolicy Dataform API 请求，该请求会向 allAuthenticatedUsers 授予对 sales 代码库的 Dataform Viewer 角色：

curl -H "Content-Type: application/json" -X POST -d '{ "policy": { "bindings": [{ "role": "roles/dataform.viewer", "members": ["allAuthenticatedUsers"]}] }}' "https://dataform.googleapis.com/v1/projects/examplepetstore/locations/us-central1/repositories/sales:setIamPolicy"

禁止公开访问代码库

如需确保不会向任何 Dataform 代码库授予公开访问权限，您可以限制项目中的 allAuthenticatedUsers 主账号。

如需限制项目中的 allAuthenticatedUsers，您可以设置 iam.allowedPolicyMemberDomains 政策，并从 allowed_values 列表中移除 allAuthenticatedUsers。

如果您在 iam.allowedPolicyMemberDomains 政策中限制 allAuthenticatedUsers，则无法在项目的任何 IAM 政策中使用 allAuthenticatedUsers 主账号，这会阻止授予对所有资源（包括 Dataform 代码库）的公开访问权限。

如需详细了解 iam.allowedPolicyMemberDomains 政策以及设置该政策的说明，请参阅按网域限制身份。

Dataform 中的员工身份联合

借助员工身份联合，您可以使用外部身份提供方 (IdP) 通过 IAM 对用户进行身份验证和授权，以便他们访问 Google Cloud 服务。

Dataform 支持员工身份联合，且没有已知限制。

使用 IAM 控制对各个表的访问权限

本部分将介绍如何为单个 Dataform 表和视图授予和撤消 BigQuery IAM 角色。

当 Dataform 运行表或视图时，会在 BigQuery 中创建相应资源。在 Dataform 中进行开发期间，您可以向单个表和视图授予 BigQuery 角色，以便在执行后控制其在 BigQuery 中的访问权限。

如需详细了解如何授予和撤消对资源的访问权限，请参阅授予对资源的访问权限。

向表或视图授予 BigQuery 角色

您可以在 Dataform 中向表或视图授予 BigQuery 角色，方法是向所选表或视图的 .sqlx 定义文件中添加包含 GRANT DCL 语句的 post_operations 块。

如需向所选表或视图授予 BigQuery 角色，请按以下步骤操作：

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

   前往 Dataform

2. 选择代码库，然后选择工作区。

3. 在文件窗格中，展开 definitions/ 目录。

4. 选择要授予访问权限的表或视图的 .sqlx 定义文件。

5. 在文件中输入以下代码段：

   post_operations {
       GRANT "ROLE_LIST"
       ON "RESOURCE_TYPE" ${self()}
       TO "USER_LIST"
   }
   

   替换以下内容：

   • ROLE_LIST：您要授予的 BigQuery 角色或以英文逗号分隔的 BigQuery 角色列表。

   • RESOURCE_TYPE：TABLE 或 VIEW。

   • USER_LIST：为其授予角色的以英文逗号分隔的用户列表。

     如需查看有效格式的列表，请参阅 user_list。

6. 可选：点击格式。

7. 运行表或视图。

8. 如果您在增量表上授予了访问权限，请在首次执行后从表定义文件中移除 GRANT 语句。

以下代码示例展示了向用户授予的表级 BigQuery 查看者角色：

config { type: "table" }

SELECT ...

post_operations {
  GRANT `roles/bigquery.dataViewer`
  ON TABLE ${self()}
  TO "user:[e-mail]"
}

撤消对表或视图的 BigQuery 角色

您可以通过以下方式撤消表或视图的 BigQuery 角色：在所选表或视图的 .sqlx 定义文件中添加包含 REVOKE DCL 语句的 post_operations 块。

如需撤消所选表或视图的 BigQuery 角色，请按以下步骤操作：

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

   前往 Dataform

2. 选择代码库，然后选择工作区。

3. 在文件窗格中，展开 definitions/ 目录。

4. 选择要撤消访问权限的表或视图的 .sqlx 定义文件。

5. 在 post_operations 代码块中，输入以下 REVOKE 语句：

       REVOKE "ROLE_LIST"
       ON "RESOURCE_TYPE" ${self()}
       FROM "USER_LIST"
   

   替换以下内容：

   • ROLE_LIST：您要撤消的 BigQuery 角色或以英文逗号分隔的 BigQuery 角色列表。
   • RESOURCE_TYPE：TABLE 或 VIEW。
   • USER_LIST：撤消角色的用户列表（以英文逗号分隔）。如需查看有效格式的列表，请参阅 user_list。

6. 如需撤消文件中 GRANT 语句授予的访问权限，请将 GRANT 语句替换为 REVOKE 语句。

   警告： 移除 GRANT 语句而不添加 REVOKE 语句不会撤消访问权限。

7. 可选：点击格式。

8. 运行表或视图。

9. 如果您撤消了对增量表的访问权限，请在首次执行后从表定义文件中移除 REVOKE 语句。

以下代码示例展示了如何撤消用户对某个表的 BigQuery 查看者角色：

config { type: "table" }

SELECT ...

post_operations {
  REVOKE `roles/bigquery.dataViewer`
  ON TABLE ${self()}
  FROM "user:[e-mail]"
}

集中管理表和视图的 BigQuery 角色

如需在一个位置控制对单个表和视图的 BigQuery 访问权限，您可以创建一个包含 GRANT 和 REVOKE DCL 语句的专用 type: "operations" 文件。

如需在单个 type: "operations" 文件中管理 BigQuery 表访问权限，请按以下步骤操作：

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

   前往 Dataform

2. 选择代码库，然后选择工作区。

3. 在文件窗格中，点击 definitions/ 旁边的 更多菜单。

4. 点击创建文件。

5. 在添加文件路径字段中，输入文件名称，然后在 definitions/ 后面输入 .sqlx。例如 definitions/table-access.sqlx。

   文件名只能包含数字、字母、连字符和下划线。

6. 点击创建文件。

7. 在文件窗格中，展开 definitions/ 目录，然后选择新创建的文件。

8. 在文件中输入以下代码段：

     config { type: "operations" }
   
     GRANT "ROLE_LIST"
     ON RESOURCE_TYPE RESOURCE_NAME
     TO "USER_LIST"
   
     REVOKE "ROLE_LIST"
     ON { "<var>" }}RESOURCE_TYPE RESOURCE_NAME
     TO "USER_LIST"
   

   替换以下内容：

   • ROLE_LIST：您要授予或撤消的 BigQuery 角色或以英文逗号分隔的 BigQuery 角色列表。
   • RESOURCE_TYPE：TABLE 或 VIEW。
   • RESOURCE_NAME：表或视图的名称。
   • USER_LIST：为其授予或撤消角色的以英文逗号分隔的用户列表。如需查看有效格式的列表，请参阅 user_list。

9. 根据需要添加 GRANT 和 REVOKE 语句。

   1. 如需撤消文件中 GRANT 语句授予的访问权限，请将 GRANT 语句替换为 REVOKE 语句。

      移除 GRANT 语句而不添加 REVOKE 语句不会撤消访问权限。

10. 可选：点击格式。

11. 每次更新后运行该文件。

    1. 如果您在增量表上授予或撤消了访问权限，请在首次执行语句后，从文件中移除 GRANT 或 REVOKE 语句。

使用 Config API 自定义 IAM 行为

您可以使用 projects.locations.updateConfig Dataform API 方法来自定义 IAM 行为并增强安全性。

警告： 您必须为要增强安全性的每个位置调用此方法。将配置应用于某个位置后，该位置中的所有 Dataform 代码库都会受到影响。如需限制可创建 Dataform 资源的位置，请参阅限制资源位置。

在创建资源时授予特定角色

如果您在 projects.locations.repositories 资源中将 setAuthenticatedUserAdmin 字段设置为 true，Dataform 会自动向创建该代码库的用户授予该代码库的 Dataform Admin 角色 (roles/dataform.admin)。此外，Dataform 还会向在该代码库中创建工作区的任何用户授予新工作区的 Dataform Admin 角色。

您可以使用 projects.locations.updateConfig 方法中的 creator_role 字段（预览）来替换此行为。如果 setAuthenticatedUserAdmin 为 true，并且您使用自定义角色配置了 creator_role 字段，则 Dataform 会授予自定义角色，而不是默认的 dataform.admin 角色。

实现增强的安排权限

预览版

此产品或功能 受服务专用条款的约束。 非正式版产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

注意： 如需提供反馈或请求支持，请联系 [e-mail]。

如需要求用户必须具有明确的权限才能安排 Dataform 工作流，请在 projects.locations.updateConfig 方法中将 enable_project_checks_for_scheduling 字段设置为 true。

为调度启用这些检查时，用户需要以下权限：

• 如需创建工作流配置，请执行以下操作：

  • 项目中的 dataform.workflowConfigs.create 权限，由 Code Scheduler 角色 (roles/dataform.codeScheduler) 授予。
  • 由 Dataform Admin 角色 (roles/dataform.admin) 授予的对代码库的 dataform.repositories.scheduleWorkflow 权限。

• 如需创建发布配置，请执行以下操作：

  • 项目中的 dataform.releaseConfigs.create 权限，由 Code Scheduler 角色 (roles/dataform.codeScheduler) 授予。
  • 由 Dataform Admin 角色 (roles/dataform.admin) 授予的对代码库的 dataform.repositories.scheduleRelease 权限。

启用私密工作区

预览版

此产品或功能 受服务专用条款的约束。 非正式版产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

注意： 如需提供反馈或请求支持，请联系 [e-mail]。

如需限制 Dataform 工作区访问权限，以便只有工作区创建者才能在该工作区中读取和写入代码，请在 projects.locations.updateConfig 方法中将 enable_private_workspace 字段设置为 true。

此限制也适用于查看生成的内容，例如工作区的编译或工作流调用的已编译 SQL、编译错误和运行日志。

此设置会替换向其他代码库用户授予工作区访问权限的标准 IAM 角色。

后续步骤

• 如需详细了解 IAM，请参阅 IAM 概览。
• 如需详细了解如何管理对资源的访问权限，请参阅管理对项目、文件夹和组织的访问权限
• 如需详细了解员工身份联合的关键概念，请参阅员工身份联合。
• 如需详细了解 BigQuery IAM 角色和权限，请参阅使用 IAM 进行访问权限控制。
• 如需详细了解如何向 BigQuery 数据集授予精细的权限，请参阅控制对数据集的访问权限。