Tag di tabelle e set di dati

Questo documento descrive come utilizzare i tag per applicare in modo condizionale i criteri di Identity and Access Management (IAM) alle tabelle e ai set di dati BigQuery.

Un tag è una coppia chiave-valore che puoi collegare direttamente a una tabella o a un set di dati oppure che una tabella o un set di dati può ereditare da altre risorse Google Cloud. Puoi applicare i criteri in modo condizionale a seconda che una risorsa abbia un tag specifico. Ad esempio, puoi concedere in modo condizionale il ruolo Visualizzatore dati BigQuery a un'entità su qualsiasi set di dati con il tag environment:dev.

Per ulteriori informazioni sull'utilizzo dei tag nella gerarchia delle risorse Google Cloud, consulta la panoramica dei tag.

Per concedere contemporaneamente le autorizzazioni a molte risorse BigQuery correlate, incluse risorse che non esistono ancora, puoi utilizzare le condizioni IAM.

Autorizzazioni obbligatorie

Per utilizzare i tag in BigQuery, devi disporre delle seguenti autorizzazioni:

• Per associare un tag a un set di dati, devi disporre dell'autorizzazione IAM bigquery.datasets.createTagBinding per il set di dati e dell'autorizzazione resourcemanager.tagValueBindings.create a livello di progetto sul valore tag che vuoi associare.
• Per associare un tag a una tabella, devi disporre dell'autorizzazione IAM bigquery.tables.createTagBinding nella tabella e dell'autorizzazione resourcemanager.tagValueBindings.create a livello di progetto sul valore tag che vuoi associare.
• Per rimuovere un tag da un set di dati, devi disporre dell'autorizzazione IAM bigquery.datasets.deleteTagBinding per il set di dati e dell'autorizzazione resourcemanager.tagValueBindings.delete a livello di progetto per il valore del tag che vuoi eliminare.
• Per rimuovere un tag da una tabella, devi disporre dell'autorizzazione IAM bigquery.tables.deleteTagBinding per la tabella e dell'autorizzazione resourcemanager.tagValueBindings.delete a livello di progetto sul valore del tag che vuoi eliminare.
• Per elencare i tag associati a un set di dati o visualizzare la sezione Tag del riquadro Modifica dettagli per un set di dati, devi disporre dell'autorizzazione IAM bigquery.datasets.listTagBindings.
• Per elencare le chiavi tag associate a un'organizzazione o un progetto principale nel riquadro Modifica dettagli per un set di dati o una tabella, devi disporre dell'autorizzazione resourcemanager.tagKeys.list a livello principale della chiave tag e dell'autorizzazione resourcemanager.tagKeys.get per ogni chiave tag.
• Per elencare i valori di tag delle chiavi associate a un'organizzazione o un progetto principale nel riquadro Modifica dettagli per un set di dati o una tabella, devi disporre dell'autorizzazione resourcemanager.tagValues.list a livello principale del valore tag e dell'autorizzazione resourcemanager.tagValues.get per ogni valore di tag.

Entrambi i seguenti ruoli IAM predefiniti includono tutte le autorizzazioni BigQuery necessarie:

• Proprietario dati BigQuery (roles/bigquery.dataOwner)
• Amministratore BigQuery (roles/bigquery.admin)

Le autorizzazioni di Resource Manager sono incluse nel ruolo Utente tag (roles/resourcemanager.tagUser).

Puoi utilizzare i tag anche per negare l'accesso in modo condizionale con criteri IAM a tabelle e set di dati BigQuery (anteprima). Per maggiori informazioni, consulta Criteri di negazione.

Creare chiavi e valori dei tag

Prima di poter associare un tag, devi crearne uno e configurarne il valore. Per creare chiavi e valori dei tag, consulta Creazione di un tag e Aggiunta di valori dei tag.

Associa i tag a un set di dati

Dopo aver creato un tag, puoi collegarlo a un set di dati. Puoi collegare un solo valore tag a un set di dati per ogni chiave tag specifica. Puoi collegare un massimo di 50 tag a un set di dati.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.

3. Nella sezione Informazioni sul set di dati, fai clic su Modifica dettagli.

4. Nella sezione Tag, seleziona i tag da aggiungere al set di dati.

   Nota: la sezione Tag non è visibile se non disponi dell'autorizzazione bigquery.datasets.listTagBindings.

5. Fai clic su Salva.

gcloud

Per collegare un tag a un set di dati utilizzando la riga di comando, crea una risorsa di associazione di tag utilizzando il comando gcloud resource-manager tags bindings create:

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Sostituisci quanto segue:

• TAGVALUE_NAME: l'ID permanente o il nome con spazio dei nomi del valore tag da collegare, come tagValues/4567890123 o 1234567/my_tag_key/my_tag_value
• RESOURCE_ID: l'ID completo del set di dati, incluso il nome di dominio dell'API (//bigquery.googleapis.com/) per identificare il tipo di risorsa, ad esempio //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: la posizione del set di dati

Elenca i tag collegati a un set di dati

I passaggi seguenti forniscono un elenco di associazioni di tag collegate direttamente a un set di dati. Non restituiscono alcun tag ereditato dalle risorse padre.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.

   I tag vengono visualizzati nella sezione Informazioni sul set di dati.

Nota: se hai l'autorizzazione bigquery.datasets.listTagBindings ma non le autorizzazioni resourcemanager.tagKeys.get e resourcemanager.tagValues.get, sarà visibile solo l'ID permanente del tag.

gcloud

Per ottenere un elenco delle associazioni di tag associate a una risorsa, utilizza il comando gcloud resource-manager tags bindings list:

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Sostituisci quanto segue:

• RESOURCE_ID: l'ID completo del set di dati, incluso il nome di dominio dell'API (//bigquery.googleapis.com/) per identificare il tipo di risorsa, ad esempio //bigquery.googleapis.com/projects/my_project/datasets/my_dataset

• LOCATION: la località del set di dati

L'output è simile al seguente:

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

Scollegare i tag da un set di dati

Puoi scollegare un tag da una risorsa eliminando la risorsa di associazione di tag. Per eliminare un tag, devi prima scollegarlo.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.

3. Nella sezione Informazioni sul set di dati, fai clic su Modifica dettagli.

4. Nella sezione Tag, fai clic su Elimina elemento accanto al tag da eliminare.

5. Fai clic su Salva.

gcloud

Per scollegare un tag da un set di dati utilizzando la riga di comando, elimina l'associazione di tag utilizzando il comando gcloud alpha resource-manager tags bindings delete:

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Sostituisci quanto segue:

• TAGVALUE_NAME: l'ID permanente o il nome con spazio dei nomi del valore tag da associare, ad esempio tagValues/4567890123 o 1234567/my_tag_key/my_tag_value
• RESOURCE_ID: l'ID completo del set di dati, incluso il nome di dominio dell'API (//bigquery.googleapis.com/) per identificare il tipo di risorsa, ad esempio //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
• LOCATION: la località del set di dati

Associa tag quando crei una nuova tabella

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Dopo aver creato un tag, puoi associarlo a una nuova tabella. Puoi collegare un solo valore tag a un set di dati per ogni chiave tag specifica. Puoi collegare un massimo di 50 tag a una tabella.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, quindi seleziona un set di dati.

3. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.

4. Inserisci le informazioni per la nuova tabella. Per maggiori dettagli, consulta Creare e utilizzare le tabelle.

5. Nella sezione Tag, seleziona i tag da aggiungere alla nuova tabella. In questo passaggio non puoi inserire manualmente gli ID tag. Puoi selezionare solo tag dal tuo progetto o dalla tua organizzazione.

6. Fai clic su Crea tabella.

bq

Utilizza il comando bq mk --table con il flag --add_tags:

bq mk --table \
    --schema=SCHEMA \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Sostituisci quanto segue:

• SCHEMA: la definizione dello schema incorporato.
• TAGS: i tag che associ alla nuova tabella, separati da virgole, ad esempio 556741164180/env:prod,myProject/department:sales. Ogni tag deve avere il nome della chiave con spazio dei nomi e il nome breve del valore.
• PROJECT_ID: l'ID del progetto in cui stai creando una tabella.
• DATASET_ID: l'ID del set di dati in cui stai creando una tabella.
• TABLE_ID: l'ID della nuova tabella che stai creando.

API

Chiama il metodo tables.insert con una risorsa di tabella definita e includi i tag nel campo resource_tags.

Associa tag a una tabella esistente

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Dopo aver creato un tag, puoi associarlo a una tabella esistente. Puoi associare un solo valore tag a una tabella per ogni chiave tag specifica. Puoi collegare un massimo di 50 tag a una tabella.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e il set di dati, poi seleziona una tabella.

3. Nella scheda Dettagli, fai clic su Modifica dettagli.

4. Nella sezione Tag, seleziona i tag da aggiungere alla tabella. In questo passaggio non puoi inserire manualmente gli ID tag. Puoi selezionare solo tag dal tuo progetto o dalla tua organizzazione.

5. Fai clic su Salva.

bq

Utilizza il comando bq update con il flag --add_tags:

bq update \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Sostituisci quanto segue:

• TAGS: i tag che associ alla tabella, separati da virgole, ad esempio 556741164180/env:prod,myProject/department:sales. Ogni tag deve avere il nome della chiave con spazio dei nomi e il nome breve del valore.
• PROJECT_ID: l'ID del progetto che contiene la tabella.
• DATASET_ID: l'ID del set di dati che contiene la tabella.
• TABLE_ID: l'ID della tabella che stai aggiornando.

API

Chiama il metodo tables.update con una risorsa di tabella definita e includi i tag nel campo resource_tags.

Elenca i tag associati a una tabella

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Puoi elencare i tag associati direttamente a una tabella. Questo processo non elenca i tag ereditati dalle risorse padre.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e il set di dati, poi seleziona una tabella.

   I tag sono visibili nella scheda Dettagli.

bq

Utilizza il comando bq show e cerca la colonna tags. Se la tabella non contiene tag, la colonna tags non viene visualizzata.

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

Sostituisci quanto segue:

• PROJECT_ID: l'ID del progetto che contiene la tabella
• DATASET_ID: l'ID del set di dati che contiene la tabella
• TABLE_ID: l'ID della tabella

API

Chiama il metodo tables.get con una risorsa di tabella definita e cerca il campo resource_tags.

Scollegare i tag da una tabella

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Puoi scollegare un tag da una tabella eliminando la risorsa di associazione di tag. Se devi eliminare un tag, devi prima scollegarlo.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e il set di dati, poi seleziona una tabella.

3. Nella scheda Dettagli, fai clic su Modifica dettagli.

4. Nella sezione Tag, rimuovi i tag che vuoi scollegare dalla tabella.

5. Fai clic su Salva.

bq

Per rimuovere alcuni tag da una tabella, utilizza il comando bq update con il flag --remove_tags:

bq update \
    --remove_tags=TAG_KEYS \
    PROJECT_ID:DATASET_ID.TABLE_ID

Sostituisci quanto segue:

• TAG_KEYS: le chiavi tag che stai scollegando dalla tabella, separate da virgole, ad esempio 556741164180/env,myProject/department. Ogni chiave tag deve avere il nome della chiave con spaziatura dei nomi.
• PROJECT_ID: l'ID del progetto che contiene la tabella.
• DATASET_ID: l'ID del set di dati che contiene la tabella.
• TABLE_ID: l'ID della tabella che stai aggiornando.

Per rimuovere tutti i tag da una tabella, utilizza il comando bq update con il flag --clear_all_tags:

bq update \
    --clear_all_tags \
    PROJECT_ID:DATASET_ID.TABLE_ID

API

Chiama il metodo tables.update con una risorsa di tabella definita e rimuovi i tag nel campo resource_tags. Per rimuovere tutti i tag, rimuovi il campo resource_tags.

Elimina tag

Non puoi eliminare un tag se fa riferimento a un set di dati o a una tabella. Prima di eliminare la chiave o il valore dei tag esistenti, devi scollegare tutte le risorse esistenti per l'associazione di tag. Per eliminare le chiavi e i valori dei tag, consulta Eliminazione dei tag.

Esempio

Supponiamo che tu sia l'amministratore di un'organizzazione. Gli analisti di dati sono tutti membri del gruppo [e-mail], che dispone del ruolo IAM Visualizzatore dati BigQuery per il progetto userData. Viene assunto un tirocinante per analista di dati che, in base ai criteri aziendali, deve avere solo l'autorizzazione per visualizzare il set di dati anonymousData nel progetto userData. Puoi controllare il loro accesso tramite i tag.

1. Crea un tag con la chiave employee_type e il valore intern:

   

2. Nella console Google Cloud, vai alla pagina IAM.

   Vai a IAM

3. Individua la riga contenente lo stagista di cui vuoi limitare l'accesso al set di dati e fai clic su Modifica entità in quella riga.

4. Nel menu Ruolo, seleziona Visualizzatore dati BigQuery.

5. Fai clic su Aggiungi condizione.

6. Nei campi Titolo e Descrizione, inserisci i valori che descrivono la condizione del tag IAM che vuoi creare.

7. Nella scheda Generatore di condizioni, fai clic su Aggiungi.

8. Nel menu Tipo di condizione, seleziona Risorsa e poi Tag.

9. Nel menu Operatore, seleziona Ha un valore.

10. Nel campo Percorso valore, inserisci il percorso del valore del tag nel formato ORGANIZATION/TAG_KEY/TAG_VALUE, ad esempio example.org/employee_type/intern.

    

    Questa condizione del tag IAM limita l'accesso dello stagista ai set di dati con il tag intern.

11. Per salvare la condizione del tag, fai clic su Salva.

12. Per salvare tutte le modifiche apportate nel riquadro Modifica autorizzazioni, fai clic su Salva.

13. Per collegare il valore tag intern al set di dati anonymousData, utilizza la riga di comando per eseguire il comando gcloud alpha resource-manager tags bindings create:

    gcloud alpha resource-manager tags bindings create \
    --tag-value=tagValues/4567890123 \
    --parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
    --location=US
    

Limitazioni

• I tag tabella non sono supportati nelle tabelle BigQuery Omni, nelle tabelle nei set di dati nascosti o nelle tabelle temporanee. Inoltre, le query tra regioni in BigQuery Omni non utilizzano i tag durante i controlli di controllo dell'accesso per le tabelle in altre regioni.

• Non puoi utilizzare i tag delle tabelle con l'API Cloud Resource Manager.

• Puoi collegare un massimo di 50 tag a un set di dati o a una tabella.

• Le query con caratteri jolly non sono supportate per le tabelle che hanno tag.

• Alcuni servizi esterni a BigQuery non possono verificare correttamente le condizioni dei tag IAM. Se la condizione del tag è positiva, ovvero se a un utente viene concesso un ruolo per una risorsa solo se la risorsa ha un tag specifico, l'accesso alla risorsa viene negato, indipendentemente dai tag associati. Se la condizione del tag è negativa, ovvero quando a un utente viene concesso un ruolo per una risorsa solo se la risorsa non ha un tag specifico, la condizione del tag non viene verificata.

  Ad esempio, Data Catalog non può verificare le condizioni dei tag IAM sui set di dati BigQuery. Supponiamo che esista un criterio IAM condizionale che assegna a uno stagista il ruolo Visualizzatore dati BigQuery sui set di dati con il tag employee_type=intern. Poiché si tratta di una condizione positiva per il tag, lo stagista non può visualizzare i set di dati eseguendo una ricerca in Data Catalog anche se questi set di dati hanno il tag employee_type=intern. Se la condizione del tag venisse modificata in una negativa, in modo che lo stagista potesse visualizzare solo i set di dati che non avevano il tag employee_type=intern, il controllo verrebbe ignorato completamente e lo stagista potrebbe visualizzare i set di dati a cui normalmente non potrebbe accedere in BigQuery.

  Best practice: utilizza condizioni di tag IAM positive piuttosto che quelle negative per evitare di concedere involontariamente ruoli.

Passaggi successivi

• Per una panoramica dei tag in Google Cloud, consulta la Panoramica dei tag.
• Per ulteriori informazioni su come utilizzare i tag, consulta Creazione e gestione dei tag.
• Per informazioni su come controllare l'accesso alle risorse BigQuery con le condizioni IAM, consulta Controllare l'accesso con le condizioni IAM.