对数据集级访问权限控制的更改
自 2026 年 3 月 17 日起，需要 bigquery.datasets.getIamPolicy Identity and Access Management (IAM) 权限才能查看数据集的访问权限控制和查询 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 视图。更新数据集的访问权限控制或使用 API 创建具有访问权限控制的数据集需要 bigquery.datasets.setIamPolicy 权限。
选择启用提前强制执行
在 2026 年 3 月 17 日之前，您可以选择启用提前强制执行权限变更。选择启用后，您需要拥有 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 权限的现有自定义角色。
如果您希望保留自定义角色的现有功能，则必须在 2026 年 3 月 17 日之前更新所有仅提供 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 响应：
| 参数值 | 所需权限 | API 响应 |
|---|---|---|
DATASET_VIEW_UNSPECIFIED（或为空） |
|
默认值。返回数据集的元数据和访问权限控制。 |
METADATA |
|
返回数据集的元数据。 |
ACL |
|
返回数据集的访问权限控制、必填字段以及数据集资源中仅用于输出的字段。 |
FULL |
|
返回数据集的元数据和访问权限控制。 |
如果您未选择启用提前强制执行，或者在选择启用后选择停用，则可以使用 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 响应：
| 参数值 | 所需权限 | API 响应 |
|---|---|---|
UPDATE_MODE_UNSPECIFIED（或为空） |
|
默认值。返回数据集更新后的元数据和访问权限控制。 |
UPDATE_METADATA |
|
返回数据集更新后的元数据。 |
UPDATE_ACL |
|
返回数据集更新后的访问权限控制、必填字段以及数据集资源中仅用于输出的字段。 |
UPDATE_FULL |
|
返回数据集更新后的元数据和访问权限控制。 |
如果您未选择启用提前强制执行，或者在选择启用后选择停用，则 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 响应：
| 参数值 | 所需权限 | API 响应 |
|---|---|---|
UPDATE_MODE_UNSPECIFIED（或为空） |
|
默认值。返回数据集更新后的元数据和访问权限控制。 |
UPDATE_METADATA |
|
返回数据集更新后的元数据。 |
UPDATE_ACL |
|
返回数据集更新后的访问权限控制、必填字段以及数据集资源中仅用于输出的字段。 |
UPDATE_FULL |
|
返回数据集更新后的元数据和访问权限控制。 |
如果您未选择启用提前强制执行，或者在选择启用后选择停用，则 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 权限。