Änderungen an Zugriffssteuerungen auf Dataset-Ebene

Ab dem 17. März 2026 ist die IAM-Berechtigung (Identity and Access Management) bigquery.datasets.getIamPolicy erforderlich, um die Zugriffssteuerung eines Datasets aufzurufen und die Ansicht INFORMATION_SCHEMA.OBJECT_PRIVILEGES abzufragen. Die Berechtigung bigquery.datasets.setIamPolicy ist erforderlich, um die Zugriffssteuerungen eines Datasets zu aktualisieren oder ein Dataset mit Zugriffssteuerungen über die API zu erstellen.

Vorzeitige Durchsetzung aktivieren

Vor dem 17. März 2026 können Sie die vorzeitige Durchsetzung der Berechtigungsänderungen aktivieren. Wenn Sie die Funktion aktivieren, ist die Berechtigung bigquery.datasets.getIamPolicy erforderlich, um die Zugriffssteuerungen eines Datasets abzurufen. Die Berechtigung bigquery.datasets.setIamPolicy ist erforderlich, um die Zugriffssteuerungen eines Datasets zu aktualisieren oder ein Dataset mit Zugriffssteuerungen über die API zu erstellen.

Wenn Sie die vorzeitige Erzwingung aktivieren möchten, legen Sie die Konfigurationseinstellung enable_fine_grained_dataset_acls_option auf Organisations- oder Projektebene auf TRUE fest. Eine Anleitung zum Aktivieren von Konfigurationseinstellungen finden Sie unter Konfigurationseinstellungen verwalten.

Beispiele für Konfigurationseinstellungen

Die folgenden Beispiele zeigen, wie Sie die Konfigurationseinstellung enable_fine_grained_dataset_acls_option festlegen und entfernen.

Organisationseinstellungen konfigurieren

Mit der DDL-Anweisung ALTER ORGANIZATION SET OPTIONS können Sie die Organisationseinstellungen konfigurieren. Im folgenden Beispiel wird enable_fine_grained_dataset_acls_option auf Organisationsebene auf TRUE festgelegt:

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

Ersetzen Sie REGION durch die Region, die Ihrer Organisation zugeordnet ist, z. B. us oder europe-west6.

Im folgenden Beispiel wird die Einstellung enable_fine_grained_dataset_acls_option auf Organisationsebene gelöscht:

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

Projekteinstellungen konfigurieren

Mit der DDL-Anweisung ALTER PROJECT SET OPTIONS können Sie Projekteinstellungen konfigurieren. Die DDL-Anweisung ALTER PROJECT SET OPTIONS akzeptiert optional die Variable project_id. Wenn project_id nicht angegeben ist, wird standardmäßig das aktuelle Projekt verwendet, in dem die Abfrage ausgeführt wird.

Im folgenden Beispiel wird für enable_fine_grained_dataset_acls_option der Wert TRUE festgelegt.

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

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

Im folgenden Beispiel wird die Einstellung enable_fine_grained_dataset_acls_option auf Projektebene gelöscht:

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

Änderungen an benutzerdefinierten Rollen

Diese Änderung der erforderlichen Berechtigungen wirkt sich auf bestehende benutzerdefinierte Rollen aus, die die Berechtigung bigquery.datasets.get, bigquery.datasets.create oder bigquery.datasets.update gewähren, aber nicht auch die Berechtigung bigquery.datasets.getIamPolicy oder bigquery.datasets.setIamPolicy.

Alle benutzerdefinierten Rollen, die nur die Berechtigung bigquery.datasets.get, bigquery.datasets.update oder bigquery.datasets.create enthalten, müssen bis zum 17. März 2026 aktualisiert werden, damit sie die Berechtigung bigquery.datasets.getIamPolicy oder bigquery.datasets.setIamPolicy enthalten, wenn Sie die vorhandene Funktionalität der benutzerdefinierten Rollen beibehalten möchten. Wenn Ihre benutzerdefinierten Rollen nur die Metadaten eines Datasets ansehen oder aktualisieren müssen, verwenden Sie die neuen Parameter dataset_view und update_mode.

Vordefinierte BigQuery-Rollen sind nicht von dieser Änderung betroffen. Alle vordefinierten Rollen, die die Berechtigung bigquery.datasets.get gewähren, gewähren auch die Berechtigung bigquery.datasets.getIamPolicy. Alle vordefinierten Rollen, die die Berechtigung bigquery.datasets.update gewähren, gewähren auch die Berechtigung bigquery.datasets.setIamPolicy.

Änderungen an Befehlen des bq-Befehlszeilentools

Wenn Sie sich für die vorzeitige Durchsetzung entscheiden, sind die folgenden bq-Tool-Befehle betroffen.

bq show

Sie können den Befehl bq show mit dem folgenden Flag verwenden:

--dataset_view={METADATA|ACL|FULL}
Gibt an, wie Berechtigungen angewendet werden, wenn Sie die Zugriffssteuerungen oder Metadaten eines Datasets ansehen. Verwenden Sie einen der folgenden Werte:
  • METADATA: Nur die Metadaten des Datasets ansehen. Für diesen Wert ist die Berechtigung bigquery.datasets.get erforderlich.
  • ACL: Nur die Zugriffssteuerung des Datasets ansehen. Für diesen Wert ist die Berechtigung bigquery.datasets.getIamPolicy erforderlich.
  • FULL: Metadaten und Zugriffssteuerungen des Datasets ansehen Für diesen Wert sind die Berechtigungen bigquery.datasets.get und bigquery.datasets.getIamPolicy erforderlich.

bq update

Sie können den Befehl bq update mit dem folgenden Flag verwenden:

--update_mode={UPDATE_METADATA|UPDATE_ACL|UPDATE_FULL}
Gibt an, wie Berechtigungen angewendet werden, wenn Sie die Zugriffssteuerungen oder Metadaten eines Datasets aktualisieren. Verwenden Sie einen der folgenden Werte:
  • UPDATE_METADATA: Nur die Metadaten des Datasets werden aktualisiert. Für diesen Wert ist die Berechtigung bigquery.datasets.update erforderlich.
  • UPDATE_ACL: Nur die Zugriffssteuerung des Datasets aktualisieren. Für diesen Wert ist die Berechtigung bigquery.datasets.setIamPolicy erforderlich.
  • UPDATE_FULL: Aktualisieren Sie sowohl die Metadaten als auch die Zugriffssteuerungen des Datasets. Für diesen Wert sind die Berechtigungen bigquery.datasets.update und bigquery.datasets.setIamPolicy erforderlich.

Änderungen an DCL-Anweisungen (Data Control Language, Datenkontrollsprache)

Wenn Sie die vorzeitige Erzwingung aktivieren, sind die folgenden Berechtigungen erforderlich, um GRANT- und REVOKE-Anweisungen für Datasets mit der Datenkontrollsprache (Data Control Language, DCL) auszuführen:

  • bigquery.datasets.setIamPolicy

Änderungen bei Abfragen für die Ansicht INFORMATION_SCHEMA

Wenn Sie die vorzeitige Erzwingung aktivieren, ist die Berechtigung bigquery.datasets.getIamPolicy erforderlich, um die Ansicht INFORMATION_SCHEMA.OBJECT_PRIVILEGES abzufragen.

Änderungen an API-Methoden

Nachdem Sie die vorzeitige Erzwingung aktiviert haben, sind die folgenden Dataset-Methoden der REST v2 API betroffen.

datasets.get-Methode

Die datasets.get-Methode hat einen zusätzlichen Pfadparameter mit dem Namen dataset_view.

Mit diesem Parameter haben Sie mehr Kontrolle über die Informationen, die von der Methode datasets.get zurückgegeben werden. Anstatt immer sowohl Zugriffssteuerungen als auch Metadaten zurückzugeben, können Sie mit dem Parameter dataset_view angeben, ob nur Metadaten, nur Zugriffssteuerungen oder beides zurückgegeben werden soll.

Das Feld access in der Dataset-Ressource enthält die Zugriffssteuerungen des Datasets. Die anderen Felder wie friendlyName, description und labels stellen die Metadaten des Datasets dar.

In der folgenden Tabelle sind die erforderliche Berechtigung und die API-Antwort für die verschiedenen Werte aufgeführt, die vom Parameter dataset_view unterstützt werden:

Parameterwert Erforderliche Berechtigungen API-Antwort
DATASET_VIEW_UNSPECIFIED (oder leer)
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 Der Standardwert. Gibt die Metadaten und Zugriffssteuerungen des Datasets zurück.
METADATA
  • bigquery.datasets.get
 Gibt die Metadaten des Datasets zurück.
ACL
  • bigquery.datasets.getIamPolicy
 Gibt die Zugriffssteuerungen, erforderlichen Felder und Felder in der Dataset-Ressource zurück, die nur ausgegeben werden.
FULL
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 Gibt die Metadaten und Zugriffssteuerungen des Datasets zurück.

Wenn Sie die vorzeitige Durchsetzung nicht aktivieren oder sie nach der Aktivierung deaktivieren, können Sie den Parameter dataset_view mit den Werten METADATA oder ACL verwenden. Die Werte FULL und DATASET_VIEW_UNSPECIFIED (oder leer) entsprechen standardmäßig dem bisherigen Verhalten. Mit der Berechtigung bigquery.datasets.get können Sie sowohl Metadaten als auch Zugriffssteuerungen abrufen.

Beispiel

Im folgenden Beispiel wird eine GET-Anfrage mit dem Parameter dataset_view, der auf METADATA festgelegt ist, gesendet:

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

Ersetzen Sie Folgendes:

  • YOUR_PROJECT: Name Ihres Projekts
  • YOUR_DATASET: der Name des Datasets
  • YOUR_API_KEY: Ihr API-Schlüssel

datasets.update-Methode

Die datasets.update-Methode hat einen zusätzlichen Pfadparameter mit dem Namen update_mode.

Mit diesem Parameter haben Sie mehr Kontrolle über die Felder, die von der Methode datasets.update aktualisiert werden. Anstatt immer Updates für Zugriffssteuerungen und Metadaten zuzulassen, können Sie mit dem Parameter update_mode angeben, ob nur Metadaten, nur Zugriffssteuerungen oder beides aktualisiert werden soll.

Das Feld access in der Dataset-Ressource enthält die Zugriffssteuerungen des Datasets. Die anderen Felder wie friendlyName, description und labels stellen die Metadaten des Datasets dar.

In der folgenden Tabelle sind die erforderliche Berechtigung und die API-Antwort für die verschiedenen Werte aufgeführt, die vom Parameter update_mode unterstützt werden:

Parameterwert Erforderliche Berechtigungen API-Antwort
UPDATE_MODE_UNSPECIFIED (oder leer)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Der Standardwert. Gibt die aktualisierten Metadaten und Zugriffssteuerungen des Datasets zurück.
UPDATE_METADATA
  • bigquery.datasets.update
 Gibt die aktualisierten Metadaten des Datasets zurück.
UPDATE_ACL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Gibt die aktualisierten Zugriffssteuerungen, Pflichtfelder und Felder in der Dataset-Ressource zurück, die nur ausgegeben werden.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Gibt die aktualisierten Metadaten und Zugriffssteuerungen des Datasets zurück.

Wenn Sie die vorzeitige Erzwingung nicht aktivieren oder sie nach der Aktivierung deaktivieren, wird in BigQuery das vorherige Verhalten verwendet. Mit der Berechtigung bigquery.datasets.update können Sie sowohl Metadaten als auch Zugriffssteuerungen aktualisieren.

Beispiel

Im folgenden Beispiel wird eine PUT-Anfrage mit dem Parameter update_mode, der auf METADATA festgelegt ist, gesendet:

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

Ersetzen Sie Folgendes:

  • YOUR_PROJECT: Name Ihres Projekts
  • YOUR_DATASET: der Name des Datasets
  • YOUR_API_KEY: Ihr API-Schlüsselname

Methode „datasets.patch“

Die datasets.patch-Methode hat einen zusätzlichen Pfadparameter mit dem Namen update_mode.

Mit diesem Parameter haben Sie mehr Kontrolle über die Felder, die von der Methode datasets.patch aktualisiert werden. Anstatt immer Updates für Zugriffssteuerungen und Metadaten zuzulassen, können Sie mit dem Parameter update_mode angeben, ob nur Metadaten, nur Zugriffssteuerungen oder beides aktualisiert werden soll.

Das Feld access in der Dataset-Ressource enthält die Zugriffssteuerungen des Datasets. Die anderen Felder wie friendlyName, description und labels stellen die Metadaten des Datasets dar.

In der folgenden Tabelle sind die erforderliche Berechtigung und die API-Antwort für die verschiedenen Werte aufgeführt, die vom Parameter update_mode unterstützt werden:

Parameterwert Erforderliche Berechtigungen API-Antwort
UPDATE_MODE_UNSPECIFIED (oder leer)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Der Standardwert. Gibt die aktualisierten Metadaten und Zugriffssteuerungen des Datasets zurück.
UPDATE_METADATA
  • bigquery.datasets.update
 Gibt die aktualisierten Metadaten des Datasets zurück.
UPDATE_ACL
  • bigquery.datasets.setIamPolicy
 Gibt die aktualisierten Zugriffssteuerungen, Pflichtfelder und Felder in der Dataset-Ressource zurück, die nur ausgegeben werden.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Gibt die aktualisierten Metadaten und Zugriffssteuerungen des Datasets zurück.

Wenn Sie die vorzeitige Erzwingung nicht aktivieren oder sie nach der Aktivierung deaktivieren, wird in BigQuery das vorherige Verhalten verwendet. Mit der Berechtigung bigquery.datasets.update können Sie sowohl Metadaten als auch Zugriffssteuerungen aktualisieren.

Beispiel

Im folgenden Beispiel wird eine PUT-Anfrage mit dem Parameter update_mode, der auf METADATA festgelegt ist, gesendet:

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

Ersetzen Sie Folgendes:

  • YOUR_PROJECT: Name Ihres Projekts
  • YOUR_DATASET: der Name des Datasets
  • YOUR_API_KEY: Ihr API-Schlüsselname

Methode „datasets.insert“

Wenn Sie sich für die vorzeitige Erzwingung entscheiden und die datasets.insert-Methode verwenden, um ein Dataset mit Zugriffssteuerungen zu erstellen, prüft BigQuery, ob dem Nutzer die Berechtigungen bigquery.datasets.create und bigquery.datasets.setIamPolicy gewährt wurden.

Wenn Sie die API verwenden, um ein Dataset ohne Zugriffssteuerung zu erstellen, ist nur die Berechtigung bigquery.datasets.create erforderlich.