Modifiche ai controlli di accesso a livello di set di dati

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

Attivare l'applicazione anticipata

Prima del 17 marzo 2026, puoi attivare l'applicazione anticipata delle modifiche alle autorizzazioni. Quando attivi questa opzione, l'autorizzazione bigquery.datasets.getIamPolicy è necessaria per ottenere i controlli dell'accesso di un set di dati e l'autorizzazione bigquery.datasets.setIamPolicy è necessaria per aggiornare i controlli dell'accesso di un set di dati o per creare un set di dati con controlli dell'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 istruzioni su come attivare le impostazioni di configurazione, vedi 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'impostazione enable_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, il valore predefinito è 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'impostazione enable_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'autorizzazione bigquery.datasets.get, bigquery.datasets.create o bigquery.datasets.update e non concedono anche l'autorizzazione bigquery.datasets.getIamPolicy o bigquery.datasets.setIamPolicy.

Qualsiasi ruolo personalizzato che includa solo l'autorizzazione bigquery.datasets.get, bigquery.datasets.update o bigquery.datasets.create deve essere aggiornato in modo da includere l'autorizzazione bigquery.datasets.getIamPolicy o bigquery.datasets.setIamPolicy entro il 17 marzo 2026, se vuoi mantenere la funzionalità esistente dei ruoli personalizzati. 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.

I ruoli predefiniti di BigQuery non sono interessati da questa modifica. Tutti i ruoli predefiniti che concedono l'autorizzazione bigquery.datasets.get concedono anche l'autorizzazione bigquery.datasets.getIamPolicy. Tutti i ruoli predefiniti che concedono l'autorizzazione bigquery.datasets.update concedono anche l'autorizzazione bigquery.datasets.setIamPolicy.

Modifiche ai comandi dello strumento a riga di comando bq

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

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 che i controlli di accesso del set di dati. Questo valore richiede l'autorizzazione 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 dell'accesso del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.setIamPolicy.
  • UPDATE_FULL: aggiorna sia i metadati che i controlli dell'accesso del set di dati. Questo valore richiede l'autorizzazione bigquery.datasets.update e bigquery.datasets.setIamPolicy.

Modifiche alle istruzioni DCL (Data Control Language)

Se attivi l'applicazione anticipata, sono necessarie le seguenti autorizzazioni per eseguire le istruzioni GRANT e REVOKE sui set di dati utilizzando il Data Control Language (DCL):

  • bigquery.datasets.setIamPolicy

Modifiche alle query di visualizzazione di INFORMATION_SCHEMA

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

Modifiche ai metodi API

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

Metodo datasets.get

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

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

Il campo access nella risorsa dataset contiene i controlli dell'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 richiesta e la risposta dell'API 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 dell'accesso, i campi obbligatori e i campi nella 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) vengono impostati per impostazione predefinita sul comportamento precedente; l'autorizzazione bigquery.datasets.get consente di ottenere sia i metadati sia i controlli dell'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 di percorso aggiuntivo denominato update_mode.

Questo parametro ti offre un maggiore controllo sui campi aggiornati dal metodo datasets.update. Anziché consentire sempre gli aggiornamenti sia dei controlli dell'accesso sia dei 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 dataset contiene i controlli dell'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 richiesta e la risposta dell'API 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 aggiornati e i controlli dell'accesso 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 di sola output aggiornati del set di dati.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Restituisce i metadati e i controlli dell'accesso aggiornati del set di dati.

Se non accetti l'applicazione anticipata o se la disattivi dopo averla attivata, BigQuery torna al comportamento precedente: l'autorizzazione bigquery.datasets.update ti consente di aggiornare sia i metadati sia i controlli dell'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 di percorso aggiuntivo denominato update_mode.

Questo parametro ti offre un maggiore controllo sui campi aggiornati dal metodo datasets.patch. Anziché consentire sempre gli aggiornamenti sia dei controlli dell'accesso sia dei 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 dataset contiene i controlli dell'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 richiesta e la risposta dell'API 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 aggiornati e i controlli dell'accesso 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 di sola output aggiornati del set di dati.
UPDATE_FULL
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
 Restituisce i metadati e i controlli dell'accesso aggiornati del set di dati.

Se non accetti l'applicazione anticipata o se la disattivi dopo averla attivata, BigQuery torna al comportamento precedente: l'autorizzazione bigquery.datasets.update ti consente di aggiornare sia i metadati sia i controlli dell'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 dell'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 dell'accesso, è richiesta solo l'autorizzazione bigquery.datasets.create.