變更資料集層級存取權控管設定

自 2025 年 9 月 15 日起，您必須具備 bigquery.datasets.getIamPolicy 身分與存取權管理 (IAM) 權限，才能查看資料集的存取權控管設定，以及查詢 INFORMATION_SCHEMA.OBJECT_PRIVILEGES 檢視畫面。您必須具備 bigquery.datasets.setIamPolicy 權限，才能更新資料集的存取權控管，或使用 API 建立含有存取權控管的資料集。

選擇提前強制執行

在 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 方法有額外的 path 參數，名為 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 方法有額外的 path 參數，名為 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 權限。