Modifiche ai controlli di accesso a livello di set di dati

A partire dal 15 settembre 2025, l'autorizzazione bigquery.datasets.getIamPolicy Identity and Access Management (IAM) è obbligatoria per visualizzare i controlli di accesso di un set di dati e eseguire query sulla INFORMATION_SCHEMA.OBJECT_PRIVILEGES vista. L'autorizzazione bigquery.datasets.setIamPolicy è necessaria per aggiornare i controlli di accesso di un set di dati o per creare un set di dati con controlli di accesso utilizzando l'API.

Attivare l'applicazione anticipata

Prima del 15 settembre 2025, puoi attivare l'applicazione anticipata delle modifiche alle autorizzazioni. Quando attivi la funzionalità, l'autorizzazione bigquery.datasets.getIamPolicy è necessaria per ottenere i controlli di accesso di un set di dati, mentre l'autorizzazione bigquery.datasets.setIamPolicy è necessaria per aggiornare i controlli di accesso di un set di dati o per creare un set di dati con controlli di accesso utilizzando l'API.

Per attivare l'applicazione anticipata, imposta l'impostazione di configurazione enable_fine_grained_dataset_acls_option su TRUE a livello di organizzazione o progetto. Per le istruzioni su come attivare le impostazioni di configurazione, consulta Gestire le impostazioni di configurazione.

Esempi di impostazioni di configurazione

Gli esempi riportati di seguito mostrano come impostare e rimuovere l'impostazione di configurazione enable_fine_grained_dataset_acls_option.

Configurare le impostazioni dell'organizzazione

Per configurare le impostazioni dell'organizzazione, utilizza l'istruzione DDL ALTER ORGANIZATION SET OPTIONS. L'esempio seguente imposta enable_fine_grained_dataset_acls_option su TRUE a livello di organizzazione:

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

Sostituisci REGION con la regione associata alla tua organizzazione, ad esempio us o europe-west6.

L'esempio seguente cancella l'impostazioneenable_fine_grained_dataset_acls_option a livello di organizzazione:

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

Configura le impostazioni del progetto

Per configurare le impostazioni del progetto, utilizza l'istruzione DDL ALTER PROJECT SET OPTIONS. L'istruzione DDL ALTER PROJECT SET OPTIONS accetta facoltativamente la variabile project_id. Se project_id non è specificato, viene utilizzato per impostazione predefinita il progetto corrente in cui viene eseguita la query.

L'esempio seguente imposta enable_fine_grained_dataset_acls_option su TRUE.

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

Sostituisci PROJECT_ID con l'ID progetto.

L'esempio seguente cancella l'impostazioneenable_fine_grained_dataset_acls_option a livello di progetto:

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

Modifiche ai ruoli personalizzati

Questa modifica alle autorizzazioni richieste influisce sui ruoli personalizzati esistenti che concedono l'autorizzazionebigquery.datasets.get, bigquery.datasets.create obigquery.datasets.update e non concedono anche l'autorizzazionebigquery.datasets.getIamPolicy o bigquery.datasets.setIamPolicy.

Se vuoi mantenere la funzionalità esistente dei ruoli personalizzati, entro il 15 settembre 2025 tutti i ruoli personalizzati che includono solo l'autorizzazione bigquery.datasets.get, bigquery.datasets.update o bigquery.datasets.create devono essere aggiornati in modo da includere l'autorizzazione bigquery.datasets.getIamPolicy o bigquery.datasets.setIamPolicy. Se i tuoi ruoli personalizzati devono visualizzare o aggiornare solo i metadati di un set di dati, utilizza i nuovi parametri dataset_view e update_mode.

Questa modifica non influisce sui ruoli predefiniti di BigQuery. Tutti i ruoli predefiniti che concedono l'autorizzazione bigquery.datasets.get concedono anche l'autorizzazione bigquery.datasets.getIamPolicy. Tutti i ruoli predefiniti che grantano l'autorizzazione bigquery.datasets.update grantano anche l'autorizzazione bigquery.datasets.setIamPolicy.

Modifiche ai comandi dello strumento a riga di comando bq

Quando attivi l'applicazione anticipata, sono interessati i seguenti comandi dello strumento bq.

bq show

Puoi utilizzare il comando bq show con il seguente flag:

--dataset_view={METADATA|ACL|FULL}
Specifica come applicare le autorizzazioni quando visualizzi i controlli di accesso o i metadati di un set di dati. Utilizza uno dei seguenti valori:
  • METADATA: visualizza solo i metadati del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.get.
  • ACL: visualizza solo i controlli di accesso del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.getIamPolicy.
  • FULL: visualizza sia i metadati sia i controlli di accesso del set di dati. Questo valore richiede le autorizzazioni bigquery.datasets.get e bigquery.datasets.getIamPolicy.

bq update

Puoi utilizzare il comando bq update con il seguente flag:

--update_mode={UPDATE_METADATA|UPDATE_ACL|UPDATE_FULL}
Specifica come applicare le autorizzazioni quando aggiorni i controlli di accesso o i metadati di un set di dati. Utilizza uno dei seguenti valori:
  • UPDATE_METADATA: aggiorna solo i metadati del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.update.
  • UPDATE_ACL: aggiorna solo i controlli di accesso del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.setIamPolicy.
  • UPDATE_FULL: aggiorna sia i metadati sia i controlli di accesso del set di dati. Questo valore richiede le autorizzazioni bigquery.datasets.update e bigquery.datasets.setIamPolicy.

Modifiche alle istruzioni DCL (Data Control Language)

Quando attivi l'applicazione anticipata, sono necessarie le seguenti autorizzazioni per eseguire istruzioni GRANT e REVOKE sui set di dati utilizzando il linguaggio di controllo dei dati (DCL):

  • bigquery.datasets.setIamPolicy

Modifiche alle query di visualizzazione INFORMATION_SCHEMA

Quando attivi l'applicazione anticipata, l'autorizzazione bigquery.datasets.getIamPolicy è obbligatoria per eseguire query sulla INFORMATION_SCHEMA.OBJECT_PRIVILEGES vista.

Modifiche ai metodi dell'API

Dopo aver attivato l'applicazione anticipata, sono interessati i seguenti metodi dei set di dati dell'API REST v2.

Metodo datasets.get

Il metodo datasets.get ha un parametro path aggiuntivo denominato dataset_view.

Questo parametro ti offre un maggiore controllo sulle informazioni restituite dal metododatasets.get. Anziché restituire sempre sia i controlli di accesso sia i metadati, il parametro dataset_view ti consente di specificare se restituire solo i metadati, solo i controlli di accesso o entrambi.

Il campo access nella risorsa set di dati contiene i controlli di accesso del set di dati. Gli altri campi, come friendlyName, description e labels, rappresentano i metadati del set di dati.

La tabella seguente mostra l'autorizzazione e la risposta dell'API richieste per i diversi valori supportati dal parametro dataset_view:

Valore parametro Autorizzazioni obbligatorie Risposta dell'API
DATASET_VIEW_UNSPECIFIED (o vuoto)
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 Il valore predefinito. Restituisce i metadati e i controlli dell'accesso del set di dati.
METADATA
  • bigquery.datasets.get
 Restituisce i metadati del set di dati.
ACL
  • bigquery.datasets.getIamPolicy
 Restituisce i controlli di accesso, i campi obbligatori e i campi della risorsa del set di dati che sono solo di output.
FULL
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
 Restituisce i metadati e i controlli dell'accesso del set di dati.

Se non attivi l'applicazione anticipata o se la disattivi dopo averla attivata, puoi utilizzare il parametro dataset_view con i valori METADATA o ACL. I valori FULL e DATASET_VIEW_UNSPECIFIED (o vuoti) prevedono per impostazione predefinita il comportamento precedente. L'autorizzazione bigquery.datasets.get ti consente di ottenere sia i metadati sia i controlli di accesso.

Esempio

L'esempio seguente invia una richiesta GET con il parametro dataset_view impostato su METADATA:

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

Sostituisci quanto segue:

  • YOUR_PROJECT: il nome del progetto
  • YOUR_DATASET: il nome del set di dati
  • YOUR_API_KEY: la tua chiave API

Metodo datasets.update

Il metodo datasets.update ha un parametro path aggiuntivo chiamato update_mode.

Questo parametro ti offre un maggiore controllo sui campi aggiornati dal metododatasets.update. Anziché consentire sempre gli aggiornamenti sia ai controlli dell'accesso sia ai metadati, il parametro update_mode ti consente di specificare se aggiornare solo i metadati, solo i controlli dell'accesso o entrambi.

Il campo access nella risorsa set di dati contiene i controlli di accesso del set di dati. Gli altri campi, come friendlyName, description e labels, rappresentano i metadati del set di dati.

La tabella seguente mostra l'autorizzazione e la risposta dell'API richieste per i diversi valori supportati dal parametro update_mode:

Valore parametro Autorizzazioni obbligatorie Risposta dell'API
UPDATE_MODE_UNSPECIFIED (o vuoto)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Il valore predefinito. Restituisce i metadati e i controlli di accesso aggiornati del set di dati.
UPDATE_METADATA
  • bigquery.datasets.update
 Restituisce i metadati aggiornati del set di dati.
UPDATE_ACL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Restituisce i controlli dell'accesso, i campi obbligatori e i campi della risorsa del set di dati aggiornati solo per l'output.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Restituisce i metadati e i controlli dell'accesso aggiornati del set di dati.

Se non attivi l'applicazione anticipata o se la disattivi dopo averla attivata, in BigQuery viene applicato per impostazione predefinita il comportamento precedente. L'autorizzazione bigquery.datasets.update ti consente di aggiornare sia i metadati sia i controlli di accesso.

Esempio

L'esempio seguente invia una richiesta PUT con il parametro update_mode impostato su METADATA:

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

Sostituisci quanto segue:

  • YOUR_PROJECT: il nome del progetto
  • YOUR_DATASET: il nome del set di dati
  • YOUR_API_KEY: il nome della tua chiave API

Metodo datasets.patch

Il metodo datasets.patch ha un parametro path aggiuntivo chiamato update_mode.

Questo parametro ti offre un maggiore controllo sui campi aggiornati dal metododatasets.patch. Anziché consentire sempre gli aggiornamenti sia ai controlli dell'accesso sia ai metadati, il parametro update_mode ti consente di specificare se aggiornare solo i metadati, solo i controlli dell'accesso o entrambi.

Il campo access nella risorsa set di dati contiene i controlli di accesso del set di dati. Gli altri campi, come friendlyName, description e labels, rappresentano i metadati del set di dati.

La tabella seguente mostra l'autorizzazione e la risposta dell'API richieste per i diversi valori supportati dal parametro update_mode:

Valore parametro Autorizzazioni obbligatorie Risposta dell'API
UPDATE_MODE_UNSPECIFIED (o vuoto)
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Il valore predefinito. Restituisce i metadati e i controlli di accesso aggiornati del set di dati.
UPDATE_METADATA
  • bigquery.datasets.update
 Restituisce i metadati aggiornati del set di dati.
UPDATE_ACL
  • bigquery.datasets.setIamPolicy
 Restituisce i controlli dell'accesso, i campi obbligatori e i campi della risorsa del set di dati aggiornati solo per l'output.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Restituisce i metadati e i controlli dell'accesso aggiornati del set di dati.

Se non attivi l'applicazione anticipata o se la disattivi dopo averla attivata, in BigQuery viene applicato per impostazione predefinita il comportamento precedente. L'autorizzazione bigquery.datasets.update ti consente di aggiornare sia i metadati sia i controlli di accesso.

Esempio

L'esempio seguente invia una richiesta PUT con il parametro update_mode impostato su METADATA:

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

Sostituisci quanto segue:

  • YOUR_PROJECT: il nome del progetto
  • YOUR_DATASET: il nome del set di dati
  • YOUR_API_KEY: il nome della tua chiave API

Metodo datasets.insert

Se attivi l'applicazione anticipata e utilizzi il metodo datasets.insert per creare un set di dati con controlli di accesso, BigQuery verifica che le autorizzazioni bigquery.datasets.create e bigquery.datasets.setIamPolicy siano concesse all'utente.

Se utilizzi l'API per creare un set di dati senza controlli di accesso, è necessaria solo l'autorizzazione bigquery.datasets.create.