对数据集级访问权限控制的更改

自 2025 年 9 月 15 日起，您需要拥有 bigquery.datasets.getIamPolicy Identity and Access Management (IAM) 权限才能查看数据集的访问权限控制和查询 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 视图。更新数据集的访问权限控制或使用 API 创建具有访问权限控制的数据集需要 bigquery.datasets.setIamPolicy 权限。

选择启用提前强制执行

在 2025 年 9 月 15 日之前，您可以选择启用提前强制执行权限变更。选择启用后，您需要拥有 bigquery.datasets.getIamPolicy 权限才能获得数据集的访问权限控制，并且需要拥有 bigquery.datasets.setIamPolicy 权限才能使用 API 更新数据集的访问权限控制或创建具有访问权限控制的数据集。

如需选择启用提前强制执行，请在组织或项目级层将 enable_fine_grained_dataset_acls_option 配置设置设为 TRUE。如需了解如何启用配置设置，请参阅管理配置设置。

配置设置示例

以下示例展示了如何设置和移除 enable_fine_grained_dataset_acls_option 配置设置。

配置组织设置

如需配置组织设置，请使用 ALTER ORGANIZATION SET OPTIONS DDL 语句。以下示例在组织级层将 enable_fine_grained_dataset_acls_option 设置为 TRUE：

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = TRUE);

将 REGION 替换为与您的组织的关联的区域，例如 us 或 europe-west6。

以下示例会清除组织级 enable_fine_grained_dataset_acls_option 设置：

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = FALSE);

配置项目设置

如需配置项目设置，请使用 ALTER PROJECT SET OPTIONS DDL 语句。ALTER PROJECT SET OPTIONS DDL 语句可以选择接受 project_id 变量。如果未指定 project_id，则默认为运行查询的当前项目。

以下示例将 enable_fine_grained_dataset_acls_option 设置为 TRUE：

ALTER PROJECT PROJECT_ID
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = TRUE);

将 PROJECT_ID 替换为您的项目 ID。

以下示例会清除项目级 enable_fine_grained_dataset_acls_option 设置：

ALTER PROJECT PROJECT_ID
SET OPTIONS (
  `region-REGION.enable_fine_grained_dataset_acls_option` = FALSE);

对自定义角色的更改

对所需权限的此项更改会影响授予 bigquery.datasets.get、bigquery.datasets.create 或 bigquery.datasets.update 权限且未同时授予 bigquery.datasets.getIamPolicy 或 bigquery.datasets.setIamPolicy 权限的现有自定义角色。

如果您希望保留自定义角色的现有功能，则必须在 2025 年 9 月 15 日之前更新所有仅提供 bigquery.datasets.get、bigquery.datasets.update 或 bigquery.datasets.create 权限的自定义角色，以便提供 bigquery.datasets.getIamPolicy 或 bigquery.datasets.setIamPolicy 权限。如果您的自定义角色需要仅查看或更新数据集的元数据，请使用新的 dataset_view 和 update_mode 参数。

BigQuery 预定义角色不受此更改的影响。所有授予 bigquery.datasets.get 权限的预定义角色也会授予 bigquery.datasets.getIamPolicy 权限。所有授予 bigquery.datasets.update 权限的预定义角色也会授予 bigquery.datasets.setIamPolicy 权限。

对 bq 命令行工具命令的更改

如果您选择启用提前强制执行，则以下 bq 工具命令会受到影响。

bq show 命令

您可以将 bq show 命令与以下标志结合使用：

--dataset_view={METADATA|ACL|FULL}

指定在查看数据集的访问权限控制或元数据时如何应用权限。请使用以下某个值：

• METADATA：仅查看数据集的元数据。此值需要 bigquery.datasets.get 权限。
• ACL：仅查看数据集的访问权限控制。此值需要 bigquery.datasets.getIamPolicy 权限。
• FULL：同时查看数据集的元数据和访问权限控制。此值需要 bigquery.datasets.get 权限和 bigquery.datasets.getIamPolicy 权限。

bq update 命令

您可以将 bq update 命令与以下标志结合使用：

--update_mode={UPDATE_METADATA|UPDATE_ACL|UPDATE_FULL}

指定在更新数据集的访问权限控制或元数据时如何应用权限。请使用以下某个值：

• UPDATE_METADATA：仅更新数据集的元数据。此值需要 bigquery.datasets.update 权限。
• UPDATE_ACL：仅更新数据集的访问权限控制。此值需要 bigquery.datasets.setIamPolicy 权限。
• UPDATE_FULL：同时更新数据集的元数据和访问权限控制。此值需要 bigquery.datasets.update 权限和 bigquery.datasets.setIamPolicy 权限。

对数据控制语言 (DCL) 语句的更改

如果您选择启用提前强制执行，则需要拥有以下权限才能使用数据控制语言 (DCL) 对数据集运行 GRANT 和 REVOKE 语句：

• bigquery.datasets.setIamPolicy

对 INFORMATION_SCHEMA 视图查询的更改

如果您选择启用提前强制执行，则需要拥有 bigquery.datasets.getIamPolicy 权限才能查询 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 视图。

对 API 方法的更改

选择启用提前强制执行后，以下 REST v2 API 数据集方法会受到影响。

datasets.get 方法

datasets.get 方法具有一个名为 dataset_view 的额外路径参数。

借助此参数，您可以更好地控制 datasets.get 方法返回的信息。dataset_view 参数可让您指定是仅返回元数据、仅返回访问权限控制，还是同时返回这两者，而不是始终同时返回访问权限控制和元数据。

数据集资源中的 access 字段包含数据集的访问权限控制。其他字段（例如 friendlyName、description 和 labels）表示数据集的元数据。

下表展示了 dataset_view 参数支持的不同值所需的权限和 API 响应：

如果您未选择启用提前强制执行，或者在选择启用后选择停用，则可以使用 dataset_view 参数并指定 METADATA 或 ACL 值。FULL 和 DATASET_VIEW_UNSPECIFIED（或为空）值默认为之前的行为；借助 bigquery.datasets.get 权限，您可以同时获取元数据和访问权限控制。

示例

以下示例会发送 GET 请求，并将 dataset_view 参数设置为 METADATA：

GET https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?datasetView=METADATA&key=YOUR_API_KEY HTTP/1.1

替换以下内容：

• YOUR_PROJECT：您的项目的名称
• YOUR_DATASET：数据集的名称
• YOUR_API_KEY：您的 API 密钥

datasets.update 方法

datasets.update 方法具有一个名为 update_mode 的额外路径参数。

借助此参数，您可以更好地控制 datasets.update 方法更新的字段。update_mode 参数可让您指定是仅更新元数据、仅更新访问权限控制，还是同时更新这两者，而不是始终允许同时更新访问权限控制和元数据。

数据集资源中的 access 字段包含数据集的访问权限控制。其他字段（例如 friendlyName、description 和 labels）表示数据集的元数据。

下表展示了 update_mode 参数支持的不同值所需的权限和 API 响应：

如果您未选择启用提前强制执行，或者在选择启用后选择停用，则 BigQuery 会默认为之前的行为；借助 bigquery.datasets.update 权限，您可以同时更新元数据和访问权限控制。

示例

以下示例会发送 PUT 请求，并将 update_mode 参数设置为 METADATA：

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

替换以下内容：

• YOUR_PROJECT：您的项目的名称
• YOUR_DATASET：数据集的名称
• YOUR_API_KEY：您的 API 密钥名称

datasets.patch 方法

datasets.patch 方法具有一个名为 update_mode 的额外路径参数。

借助此参数，您可以更好地控制 datasets.patch 方法更新的字段。update_mode 参数可让您指定是仅更新元数据、仅更新访问权限控制，还是同时更新这两者，而不是始终允许同时更新访问权限控制和元数据。

数据集资源中的 access 字段包含数据集的访问权限控制。其他字段（例如 friendlyName、description 和 labels）表示数据集的元数据。

下表展示了 update_mode 参数支持的不同值所需的权限和 API 响应：

如果您未选择启用提前强制执行，或者在选择启用后选择停用，则 BigQuery 会默认为之前的行为；借助 bigquery.datasets.update 权限，您可以同时更新元数据和访问权限控制。

示例

以下示例会发送 PUT 请求，并将 update_mode 参数设置为 METADATA：

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

替换以下内容：

• YOUR_PROJECT：您的项目的名称
• YOUR_DATASET：数据集的名称
• YOUR_API_KEY：您的 API 密钥名称

datasets.insert 方法

如果您选择启用提前强制执行，并使用 datasets.insert 方法创建具有访问权限控制的数据集，则 BigQuery 会验证是否已向用户授予 bigquery.datasets.create 和 bigquery.datasets.setIamPolicy 权限。

如果您使用 API 创建不具有访问权限控制的数据集，则只需要 bigquery.datasets.create 权限。