使用 IAM 控制对资源的访问权限

本文档介绍了如何查看资源的当前访问权限政策、如何授予资源访问权限以及如何撤消对资源的访问权限。

本文档假定您熟悉 Google Cloud 中的 Identity and Access Management (IAM) 系统。

所需的角色

如需获取修改资源 IAM 政策所需的权限，请让您的管理员授予您项目的 BigQuery Data Owner (roles/bigquery.dataOwner) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含修改资源 IAM 政策所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能修改资源 IAM 政策：

• 获取数据集的访问权限政策： bigquery.datasets.get
• 设置数据集的访问权限政策： bigquery.datasets.update
• 获取数据集的访问权限政策（仅限 Google Cloud 控制台）： bigquery.datasets.getIamPolicy
• 设置数据集的访问权限政策（仅限控制台）： bigquery.datasets.setIamPolicy
• 获取表或视图的访问权限政策： bigquery.tables.getIamPolicy
• 设置表或视图的政策： bigquery.tables.setIamPolicy
• 创建 bq 工具或 SQL BigQuery 作业（可选）： bigquery.jobs.create

您也可以使用自定义角色或其他预定义角色来获取这些权限。

查看资源的访问权限政策

以下部分介绍如何查看不同资源的访问权限政策。

查看数据集的访问权限政策

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目，然后选择数据集。

3. 点击 共享 > 权限。

   数据集访问权限政策会显示在数据集权限窗格中。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 要获取现有政策并将其输出到 JSON 格式的本地文件，请使用 Cloud Shell 中的 bq show 命令：

   bq show \
      --format=prettyjson \
      PROJECT_ID:DATASET > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：您的数据集的名称。
   • PATH_TO_FILE：本地机器上 JSON 文件的路径

API

如需查看数据集的访问权限政策，请使用定义的 dataset 资源调用 datasets.get 方法。

该政策可在返回的 dataset 资源的 access 属性中找到。

查看表或视图的访问权限政策

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目并选择表或视图。

3. 点击 共享。

   表或视图访问权限政策将显示在共享窗格中。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 要获取现有访问权限政策并将其输出到 JSON 格式的本地文件，请使用 Cloud Shell 中的 bq get-iam-policy 命令：

   bq get-iam-policy \
      --table=true \
      PROJECT_ID:DATASET.RESOURCE > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：您的数据集的名称。
   • RESOURCE：您要查看其政策的表或视图的名称
   • PATH_TO_FILE：本地机器上 JSON 文件的路径

API

如需检索当前政策，请调用 tables.getIamPolicy 方法。

注意：对于视图，请在此 API 调用中使用 tables 作为 resource。

授予对资源的访问权限

以下部分介绍了如何授予对不同资源的访问权限。

注意：授予对数据集或表的访问权限不会自动在探索器窗格中列出它们。如需在探索器窗格中查看项目，请参阅为项目加星标。

授予对数据集的访问权限

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目并选择要共享的数据集。

3. 点击 共享 > 权限。

4. 点击 添加主账号。

5. 在新的主账号字段中，输入主账号。

6. 在选择角色列表中，选择预定义角色或自定义角色。

7. 点击保存。

8. 要返回数据集信息，请点击关闭。

SQL

如需向主账号授予对数据集的访问权限，请使用 GRANT DCL 语句：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   GRANT `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   TO "USER_LIST"

   请替换以下内容：

   • ROLE_LIST：您要授予权限的角色或以英文逗号分隔的角色列表
   • RESOURCE_NAME：您要向其授予权限的资源的名称

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

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

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

以下示例会针对数据集 myDataset 授予 Data Viewer 角色：

GRANT `roles/bigquery.dataViewer`
ON SCHEMA `myProject`.myDataset
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 要将现有数据集信息（包括访问权限控制设置）写入 JSON 文件，请使用 bq show 命令：

   bq show \
      --format=prettyjson \
      PROJECT_ID:DATASET > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：您的数据集的名称。
   • PATH_TO_FILE：本地机器上 JSON 文件的路径

3. 对 JSON 文件的 access 部分进行更改。您可以将其添加到任何 specialGroup 条目：projectOwners、projectWriters、projectReaders、allAuthenticatedUsers。您还可以添加以下任一项：userByEmail、groupByEmail、domain。

   例如，数据集 JSON 文件的 access 部分可能如下所示：

   {
    "access": [
     {
      "role": "READER",
      "specialGroup": "projectReaders"
     },
     {
      "role": "WRITER",
      "specialGroup": "projectWriters"
     },
     {
      "role": "OWNER",
      "specialGroup": "projectOwners"
     },
     {
      "role": "READER",
      "specialGroup": "allAuthenticatedUsers"
     },
     {
      "role": "READER",
      "domain": "domain_name"
     },
     {
      "role": "WRITER",
      "userByEmail": "user_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }

4. 修改完成后，运行 bq update 命令，并用 --source 标志包括该 JSON 文件。如果数据集不属于默认项目，请按以下格式将相应项目 ID 添加到数据集名称中：PROJECT_ID:DATASET。

   注意：包含访问权限控制设置的 JSON 文件生效后，现有的设置将被覆盖。

   bq update \
   --source PATH_TO_FILE \
   PROJECT_ID:DATASET

5. 如需验证您的访问权限控制发生了变化，请再次使用 bq show 命令，但不要将信息写入文件：

   bq show --format=prettyjson PROJECT_ID:DATASET

Terraform

使用 google_bigquery_dataset_iam 资源可更新对数据集的访问权限。

重要提示：google_bigquery_dataset_iam 提供的不同资源可能会相互冲突，也可能会与 google_bigquery_dataset_access 资源冲突。我们建议您先仔细阅读 google_bigquery_dataset_iam 文档，然后再使用 Terraform 进行访问权限控制更改。

为数据集设置访问权限政策

以下示例展示了如何使用 google_bigquery_dataset_iam_policy 资源为 mydataset 数据集设置 IAM 政策。这会替换已附加到该数据集的任何现有政策：

# This file sets the IAM policy for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.admin"
    members = [
      "user:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "group:[e-mail]",
    ]
  }
  binding {
    role = "roles/bigquery.dataEditor"
    members = [
      "serviceAccount:[e-mail]",
    ]
  }
}

resource "google_bigquery_dataset_iam_policy" "dataset_iam_policy" {
  dataset_id  = google_bigquery_dataset.default.dataset_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

为数据集设置角色成员资格

以下示例展示了如何使用 google_bigquery_dataset_iam_binding 资源为 mydataset 数据集设置给定角色的成员资格。这会替换该角色中的任何现有成员资格。数据集 IAM 政策中的其他角色会保留：

# This file sets membership in an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_binding" "dataset_iam_binding" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.jobUser"

  members = [
    "user:[e-mail]",
    "group:[e-mail]"
  ]
}

为单个主账号设置角色成员资格

以下示例展示了如何使用 google_bigquery_dataset_iam_member 资源更新 mydataset 数据集的 IAM 政策，以向一个主账号授予角色。更新此 IAM 政策不会影响已针对相应数据集授予该角色的任何其他主账号的访问权限。

# This file adds a member to an IAM role for the dataset created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" dataset resource with a dataset_id of "mydataset".

resource "google_bigquery_dataset_iam_member" "dataset_iam_member" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  role       = "roles/bigquery.user"
  member     = "user:[e-mail]"
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

API

要在创建数据集时应用访问权限控制，请使用已定义的数据集资源来调用 datasets.insert 方法。要更新访问权限控制，请调用 datasets.patch 方法并使用 Dataset 资源中的 access 属性。

由于 datasets.update 方法会替换整个数据集资源，因此 datasets.patch 是更新访问权限控制的首选方法。

Go

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Go 设置说明进行操作。 如需了解详情，请参阅 BigQuery Go API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateDatasetAccessControl demonstrates how the access control policy of a dataset
// can be amended by adding an additional entry corresponding to a specific user identity.
func updateDatasetAccessControl(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}
	// Append a new access control entry to the existing access list.
	update := bigquery.DatasetMetadataToUpdate{
		Access: append(meta.Access, &bigquery.AccessEntry{
			Role:       bigquery.ReaderRole,
			EntityType: bigquery.UserEmailEntity,
			Entity:     "[e-mail]"},
		),
	}

	// Leverage the ETag for the update to assert there's been no modifications to the
	// dataset since the metadata was originally read.
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。 如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.bigquery.Acl;
import com.google.cloud.bigquery.Acl.Role;
import com.google.cloud.bigquery.Acl.User;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.ArrayList;

public class UpdateDatasetAccess {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    // Create a new ACL granting the READER role to "[e-mail]"
    // For more information on the types of ACLs available see:
    // https://cloud.google.com/storage/docs/access-control/lists
    Acl newEntry = Acl.of(new User("[e-mail]"), Role.READER);

    updateDatasetAccess(datasetName, newEntry);
  }

  public static void updateDatasetAccess(String datasetName, Acl newEntry) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Dataset dataset = bigquery.getDataset(datasetName);

      // Get a copy of the ACLs list from the dataset and append the new entry
      ArrayList<Acl> acls = new ArrayList<>(dataset.getAcl());
      acls.add(newEntry);

      bigquery.update(dataset.toBuilder().setAcl(acls).build());
      System.out.println("Dataset Access Control updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset Access control was not updated \n" + e.toString());
    }
  }
}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

使用数据集的访问权限控制来设置 dataset.access_entries 属性。然后调用 client.update_dataset() 函数以更新该属性。

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom
# you are adding access. Alternatively, to the JSON REST API representation
# of the entity, such as a view's table reference.
entity_id = "[e-mail]"

from google.cloud.bigquery.enums import EntityTypes

# TODO(developer): Set entity_type to the type of entity you are granting access to.
# Common types include:
#
# * "userByEmail" -- A single user or service account. For example "[e-mail]"
# * "groupByEmail" -- A group of users. For example "[e-mail]"
# * "view" -- An authorized view. For example
#       {"projectId": "p", "datasetId": "d", "tableId": "v"}
#
# For a complete reference, see the REST API reference documentation:
# https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#Dataset.FIELDS.access
entity_type = EntityTypes.GROUP_BY_EMAIL

# TODO(developer): Set role to a one of the "Basic roles for datasets"
# described here:
# https://cloud.google.com/bigquery/docs/access-control-basic-roles#dataset-basic-roles
role = "READER"

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
entries.append(
    bigquery.AccessEntry(
        role=role,
        entity_type=entity_type,
        entity_id=entity_id,
    )
)
dataset.access_entries = entries

dataset = client.update_dataset(dataset, ["access_entries"])  # Make an API request.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

授予对表或视图的访问权限

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目，然后选择要共享的表或视图。

3. 点击 共享。

4. 点击 添加主账号。

5. 在新的主账号字段中，输入主账号。

6. 在选择角色列表中，选择预定义角色或自定义角色。

7. 点击保存。

8. 要返回以查看表或视图详细信息，请点击关闭。

SQL

如需向主账号授予对表或视图的访问权限，请使用 GRANT DCL 语句：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   GRANT `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   TO "USER_LIST"

   请替换以下内容：

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

   • RESOURCE_TYPE：角色适用的资源类型

     支持的值包括 TABLE、VIEW、MATERIALIZED VIEW 和 EXTERNAL TABLE。

   • RESOURCE_NAME：您要向其授予权限的资源的名称

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

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

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

以下示例会针对表 myTable 授予 Data Viewer 角色：

GRANT `roles/bigquery.dataViewer`
ON TABLE `myProject`.myDataset.myTable
TO "user:[e-mail]", "user:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如需将现有表或视图信息（包括访问权限控制设置）写入 JSON 文件，请使用 bq get-iam-policy 命令：

   bq get-iam-policy \
      PROJECT_ID:DATASET.TABLE_OR_VIEW \
      > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：包含要更新的表或视图的数据集的名称
   • TABLE_OR_VIEW：要更新的资源的名称
   • PATH_TO_FILE：本地机器上 JSON 文件的路径
   注意：设置政策时，始终应先检索当前政策，以获取 etag 的当前值。更新后的政策文件必须包含与您要替换的当前政策相同的 etag 值，否则更新将会失败。此功能可防止发生并发更新。
   
   在政策文件中，version 的值仍为 1。此版本号指的是 IAM 政策架构版本，而不是政策版本。etag 值是政策版本号。

3. 对 JSON 文件的 bindings 部分进行更改。绑定会将一个或多个 members 或主账号绑定到单个 role。主账号可以是用户账号、服务账号、Google 群组和网域。例如，表或视图的 JSON 文件的 bindings 部分可能如下所示：

   {
     "bindings": [
       {
         "role": "roles/bigquery.dataViewer",
         "members": [
           "user:[e-mail]",
           "group:[e-mail]",
           "domain:google.com",
           "serviceAccount:[e-mail]"
         ]
       },
     ],
     "etag": "BwWWja0YfJA=",
     "version": 1
   }

   注意：不允许没有任何成员的空绑定，这样的空绑定将导致错误。

4. 如需更新访问政策，请使用 bq set-iam-policy 命令：

   bq set-iam-policy PROJECT_ID:DATASET.TABLE_OR_VIEW PATH_TO_FILE

5. 如需验证您的访问权限控制发生了变化，请再次使用 bq get-iam-policy 命令，但不要将信息写入文件。

   bq get-iam-policy --format=prettyjson \
       PROJECT_ID:DATASET.TABLE_OR_VIEW

Terraform

使用 google_bigquery_table_iam 资源可更新对表的访问权限。

重要提示：google_bigquery_table_iam 提供的不同资源可能会相互冲突。我们建议您先仔细阅读 google_bigquery_table_iam 文档，然后再使用 Terraform 进行访问权限控制更改。

为表设置访问权限政策

以下示例展示了如何使用 google_bigquery_table_iam_policy 资源为 mytable 为设置 IAM 政策。这会替换已附加到该表的任何现有政策：

# This file sets the IAM policy for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

data "google_iam_policy" "iam_policy" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:[e-mail]",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "table_iam_policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.iam_policy.policy_data
}

为表设置角色成员资格

以下示例展示了如何使用 google_bigquery_table_iam_binding 资源为 mytable 表设置给定角色的成员资格。这会替换该角色中的任何现有成员资格。表 IAM 政策中的其他角色会保留。

# This file sets membership in an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_binding" "table_iam_binding" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataOwner"

  members = [
    "group:[e-mail]",
  ]
}

为单个主账号设置角色成员资格

以下示例展示了如何使用 google_bigquery_table_iam_member 资源更新 mytable 表的 IAM 政策，以向一个主账号授予角色。更新此 IAM 政策不会影响已针对相应数据集授予该角色的任何其他主账号的访问权限。

# This file adds a member to an IAM role for the table created by
# https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_table/main.tf.
# You must place it in the same local directory as that main.tf file,
# and you must have already applied that main.tf file to create
# the "default" table resource with a table_id of "mytable".

resource "google_bigquery_table_iam_member" "table_iam_member" {
  dataset_id = google_bigquery_table.default.dataset_id
  table_id   = google_bigquery_table.default.table_id
  role       = "roles/bigquery.dataEditor"
  member     = "serviceAccount:[e-mail]"
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

API

1. 如需检索当前政策，请调用 tables.getIamPolicy 方法。

2. 修改该政策以添加成员和/或绑定。如需了解政策所需的格式，请参阅政策参考主题。

   注意：设置政策时，始终应先检索当前政策，以获取 etag 的当前值。更新后的政策文件必须包含与您要替换的当前政策相同的 etag 值，否则更新将会失败。此功能可防止发生并发更新。
   
   在政策文件中，version 的值仍为 1。此版本号指的是 IAM 政策架构版本，而不是政策版本。etag 值是政策版本号。

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。 如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;

// Sample to create iam policy for table
public class CreateIamPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createIamPolicy(datasetName, tableName);
  }

  public static void createIamPolicy(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      Policy policy = bigquery.getIamPolicy(tableId);
      policy
          .toBuilder()
          .addIdentity(Role.of("roles/bigquery.dataViewer"), Identity.allUsers())
          .build();
      bigquery.setIamPolicy(tableId, policy);
      System.out.println("Iam policy created successfully");
    } catch (BigQueryException e) {
      System.out.println("Iam policy was not created. \n" + e.toString());
    }
  }
}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

from google.cloud import bigquery

bqclient = bigquery.Client()

policy = bqclient.get_iam_policy(
    your_table_id,  # e.g. "project.dataset.table"
)

analyst_email = "[e-mail]"
binding = {
    "role": "roles/bigquery.dataViewer",
    "members": {f"group:{analyst_email}"},
}
policy.bindings.append(binding)

updated_policy = bqclient.set_iam_policy(
    your_table_id,  # e.g. "project.dataset.table"
    policy,
)

for binding in updated_policy.bindings:
    print(repr(binding))

撤消对资源的访问权限

以下部分介绍如何撤消对不同资源的访问权限。

撤消对数据集的访问权限

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器面板中，展开您的项目并选择数据集。

3. 在详细信息面板中，点击共享 > 权限。

4. 在数据集权限对话框中，展开要撤消其访问权限的主账号。

5. 点击 移除主账号。

6. 在从主账号中移除角色？对话框中，点击移除。

7. 要返回数据集详细信息，请点击关闭。

注意：如果无法以这种方式撤消访问权限，主账号可能是从资源层次结构的更高级别继承的访问权限。 如需了解如何修改主账号访问权限，请参阅授予或撤消单个角色。

SQL

如需移除主账号对数据集的访问权限，请使用 REVOKE DCL 语句：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   REVOKE `ROLE_LIST`
   ON SCHEMA RESOURCE_NAME
   FROM "USER_LIST"

   请替换以下内容：

   • ROLE_LIST：您要撤消权限的角色或以英文逗号分隔的角色列表
   • RESOURCE_NAME：您要撤消其权限的资源的名称

   • USER_LIST：将撤消其角色的以英文逗号分隔的用户列表

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

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

以下示例会撤消数据集 myDataset 的管理员角色：

REVOKE `roles/bigquery.admin`
ON SCHEMA `myProject`.myDataset
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 要将现有数据集信息（包括访问权限控制设置）写入 JSON 文件，请使用 bq show 命令：

   bq show \
     --format=prettyjson \
     PROJECT_ID:DATASET > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：您的数据集的名称。
   • PATH_TO_FILE：本地机器上 JSON 文件的路径

3. 对 JSON 文件的 access 部分进行更改。您可以移除以下任何 specialGroup 条目：projectOwners、projectWriters、projectReaders 和 allAuthenticatedUsers。您还可以移除以下任何一项：userByEmail、groupByEmail 和 domain。

   例如，数据集 JSON 文件的 access 部分可能如下所示：

   {
    "access": [
     {
      "role": "READER",
      "specialGroup": "projectReaders"
     },
     {
      "role": "WRITER",
      "specialGroup": "projectWriters"
     },
     {
      "role": "OWNER",
      "specialGroup": "projectOwners"
     },
     {
      "role": "READER",
      "specialGroup": "allAuthenticatedUsers"
     },
     {
      "role": "READER",
      "domain": "domain_name"
     },
     {
      "role": "WRITER",
      "userByEmail": "user_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }

4. 修改完成后，运行 bq update 命令，并用 --source 标志包括该 JSON 文件。如果数据集不属于默认项目，请按以下格式将相应项目 ID 添加到数据集名称中：PROJECT_ID:DATASET。

   注意：包含访问权限控制设置的 JSON 文件生效后，现有的设置将被覆盖。

   bq update \
       --source PATH_TO_FILE \
       PROJECT_ID:DATASET

5. 如需验证您的访问权限控制发生了变化，请再次使用 show 命令，但不要将信息写入文件：

   bq show --format=prettyjson PROJECT_ID:DATASET

API

调用 datasets.patch 并使用 Dataset 资源中的 access 属性更新访问权限控制。

由于 datasets.update 方法会替换整个数据集资源，因此 datasets.patch 是更新访问权限控制的首选方法。

Go

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Go 设置说明进行操作。 如需了解详情，请参阅 BigQuery Go API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// revokeDatasetAccess updates the access control on a dataset to remove all
// access entries that reference a specific entity.
func revokeDatasetAccess(projectID, datasetID, entity string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// entity := "[e-mail]"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	var newAccessList []*bigquery.AccessEntry
	for _, entry := range meta.Access {
		if entry.Entity != entity {
			newAccessList = append(newAccessList, entry)
		}
	}

	// Only proceed with update if something in the access list was removed.
	// Additionally, we use the ETag from the initial metadata to ensure no
	// other changes were made to the access list in the interim.
	if len(newAccessList) < len(meta.Access) {

		update := bigquery.DatasetMetadataToUpdate{
			Access: newAccessList,
		}
		if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
			return err
		}
	}
	return nil
}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。 如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

使用数据集的访问权限控制来设置 dataset.access_entries 属性。然后调用 client.update_dataset() 函数以更新该属性。

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
dataset_id = "your-project.your_dataset"

# TODO(developer): Set entity_id to the ID of the email or group from whom you are revoking access.
entity_id = "[e-mail]"

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

dataset = client.get_dataset(dataset_id)  # Make an API request.

entries = list(dataset.access_entries)
dataset.access_entries = [
    entry for entry in entries if entry.entity_id != entity_id
]

dataset = client.update_dataset(
    dataset,
    # Update just the `access_entries` property of the dataset.
    ["access_entries"],
)  # Make an API request.

full_dataset_id = f"{dataset.project}.{dataset.dataset_id}"
print(f"Revoked dataset access for '{entity_id}' to ' dataset '{full_dataset_id}.'")

撤消对表或视图的访问权限

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器面板中，展开您的项目并选择表或视图。

3. 在详细信息面板中，点击共享。

4. 在共享对话框中，展开要撤消其访问权限的主账号。

5. 点击 删除。

6. 在从主账号中移除角色？对话框中，点击移除。

7. 要返回以查看表或视图详细信息，请点击关闭。

注意：如果无法以这种方式撤消访问权限，主账号可能是从资源层次结构的更高级别继承的访问权限。 如需了解如何修改主账号访问权限，请参阅授予或撤消单个角色。

SQL

如需移除主账号对表或视图的访问权限，请使用 REVOKE DCL 语句：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中，输入以下语句：

   REVOKE `ROLE_LIST`
   ON RESOURCE_TYPE RESOURCE_NAME
   FROM "USER_LIST"

   请替换以下内容：

   • ROLE_LIST：您要撤消权限的角色或以英文逗号分隔的角色列表

   • RESOURCE_TYPE：从中撤消角色权限的资源类型

     支持的值包括 TABLE、VIEW、MATERIALIZED VIEW 和 EXTERNAL TABLE。

   • RESOURCE_NAME：您要撤消其权限的资源的名称

   • USER_LIST：将撤消其角色的以英文逗号分隔的用户列表

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

3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

以下示例会撤消表 myTable 的管理员角色：

REVOKE `roles/bigquery.admin`
ON TABLE `myProject`.myDataset.myTable
FROM "group:[e-mail]", "serviceAccount:[e-mail]"

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如需将现有表或视图信息（包括访问权限控制设置）写入 JSON 文件，请使用 bq get-iam-policy 命令：

   bq get-iam-policy \
      PROJECT_ID:DATASET.TABLE_OR_VIEW \
      > PATH_TO_FILE

   请替换以下内容：

   • PROJECT_ID：您的项目 ID
   • DATASET：包含要更新的表或视图的数据集的名称
   • TABLE_OR_VIEW：要更新的资源的名称

   • PATH_TO_FILE：本地机器上 JSON 文件的路径

     注意：设置政策时，始终应先检索当前政策，以获取 etag 的当前值。更新后的政策文件必须包含与您要替换的当前政策相同的 etag 值，否则更新将会失败。此功能可防止发生并发更新。
     
     在政策文件中，version 的值仍为 1。此编号指的是 IAM 政策架构版本，而不是政策版本。etag 值是政策版本号。

3. 对 JSON 文件的 access 部分进行更改。您可以移除以下任何 specialGroup 条目：projectOwners、projectWriters、projectReaders 和 allAuthenticatedUsers。您还可以移除以下任何一项：userByEmail、groupByEmail 和 domain。 例如，表或视图的 JSON 文件的 access 部分可能如下所示：

   {
    "access": [
     {
      "role": "READER",
      "specialGroup": "projectReaders"
     },
     {
      "role": "WRITER",
      "specialGroup": "projectWriters"
     },
     {
      "role": "OWNER",
      "specialGroup": "projectOwners"
     },
     {
      "role": "READER",
      "specialGroup": "allAuthenticatedUsers"
     },
     {
      "role": "READER",
      "domain": "domain_name"
     },
     {
      "role": "WRITER",
      "userByEmail": "user_email"
     },
     {
      "role": "READER",
      "groupByEmail": "group_email"
     }
    ],
    ...
   }

   注意：不允许没有任何成员的空绑定，这样的空绑定将导致错误。

4. 如需更新访问政策，请使用 bq set-iam-policy 命令：

    bq set-iam-policy PROJECT_ID:DATASET.TABLE_OR_VIEW PATH_TO_FILE

5. 如需验证您的访问权限控制发生了变化，请再次使用 get-iam-policy 命令，但不要将信息写入文件：

   bq get-iam-policy --format=prettyjson \
       PROJECT_ID:DATASET.TABLE_OR_VIEW

API

1. 如需检索当前政策，请调用 tables.getIamPolicy 方法。

2. 修改政策以移除成员和/或绑定。如需了解政策所需的格式，请参阅政策参考主题。

   注意：设置政策时，始终应先检索当前政策，以获取 etag 的当前值。更新后的政策文件必须包含与您要替换的当前政策相同的 etag 值，否则更新将会失败。此功能可防止发生并发更新。
   
   在政策文件中，version 的值仍为 1。此版本号指的是 IAM 政策架构版本，而不是政策版本。etag 值是政策版本号。

3. 调用 tables.setIamPolicy 以写入更新后的政策。 注意：不允许没有任何成员的空绑定，这样的空绑定将导致错误。

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。 如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.Identity;
import com.google.cloud.Policy;
import com.google.cloud.Role;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;

// Sample to update iam policy in table
public class UpdateIamPolicy {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    updateIamPolicy(datasetName, tableName);
  }

  public static void updateIamPolicy(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      Policy policy = bigquery.getIamPolicy(tableId);
      Map<Role, Set<Identity>> binding = new HashMap<>(policy.getBindings());
      binding.remove(Role.of("roles/bigquery.dataViewer"));

      policy.toBuilder().setBindings(binding).build();
      bigquery.setIamPolicy(tableId, policy);

      System.out.println("Iam policy updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Iam policy was not updated. \n" + e.toString());
    }
  }
}

拒绝访问资源

预览

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

注意：如需针对此预览版提供反馈或提出问题，请联系 [e-mail]。

通过 IAM 拒绝政策，您可以设置关于访问 BigQuery 资源的安全措施。您可以定义拒绝规则，以防止所选主账号使用特定权限（无论主账号被授予哪些角色）。

如需了解如何创建、更新和删除拒绝访问政策，请参阅拒绝访问资源。

特殊情况

在针对一些 BigQuery 权限创建 IAM 拒绝政策时，请考虑以下场景：

• 对授权资源（视图、routines、数据集或存储过程）的访问权限可让您create、删除或操纵表，以及读取和修改表数据（即使您没有执行这些操作的直接权限）。它还可以获取模型数据或元数据，并针对底层表调用其他存储过程。此能力意味着授权资源具有以下权限：

  • bigquery.tables.get
  • bigquery.tables.list
  • bigquery.tables.getData
  • bigquery.tables.updateData
  • bigquery.tables.create
  • bigquery.tables.delete
  • bigquery.routines.get
  • bigquery.routines.list
  • bigquery.datasets.get
  • bigquery.models.getData
  • bigquery.models.getMetadata

  如需拒绝访问这些授权资源，请在创建拒绝访问政策时将以下任一值添加到 deniedPrincipal 字段中：

  值	使用场景
  principalSet://goog/public:all	阻止所有主账号，包括授权资源。
  principalSet://bigquery.googleapis.com/projects/PROJECT_NUMBER/*	阻止指定项目中的所有 BigQuery 授权资源。PROJECT_NUMBER 是系统为 INT64 类型的项目自动生成的唯一标识符。

• BigQuery 会将作业所有者的查询结果缓存 24 小时，作业所有者可以访问这些结果，而无需对包含数据的表拥有 bigquery.tables.getData 权限。因此，针对 bigquery.tables.getData 权限添加 IAM 拒绝政策不会阻止作业所有者访问缓存结果（除非缓存到期）。如需阻止作业所有者访问缓存结果，请针对 bigquery.jobs.create 权限创建单独的拒绝政策。