Aggiunta di etichette alle risorse
Questa pagina spiega come etichettare le risorse BigQuery.
Prima di iniziare
Concedi ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento. Tutte le autorizzazioni necessarie per eseguire un'attività sono elencate nella sezione "Ruoli IAM richiesti" dell'attività.
aggiungi etichette ai set di dati
È possibile aggiungere un'etichetta a un set di dati BigQuery quando viene creata utilizzando il comando bq mk
dello strumento a riga di comando bq o chiamando il metodo API datasets.insert
. Attualmente, non puoi aggiungere un'etichetta a un set di dati quando viene creato utilizzando
la console Google Cloud.
Questa pagina illustra come aggiungere un'etichetta a un set di dati dopo averlo creato. Per ulteriori informazioni sull'aggiunta di un'etichetta quando crei un set di dati, consulta Creazione di un set di dati.
È possibile aggiungere un'etichetta dopo la creazione di un set di dati:
- Utilizzo della console Google Cloud
- Utilizzo delle istruzioni DDL SQL
- Utilizzo del comando
bq update
dello strumento a riga di comando bq - Chiamata al metodo API
datasets.patch
- Utilizzo delle librerie client
Quando aggiungi un'etichetta a un set di dati, questa non si propaga alle risorse all'interno del set di dati. Le etichette del set di dati non vengono ereditate dalle tabelle o dalle viste. Inoltre, quando aggiungi un'etichetta a un set di dati, questa viene inclusa nei dati di fatturazione dello spazio di archiviazione, ma non nei dati di fatturazione relativi al job.
Per ulteriori dettagli sul formato di un'etichetta, consulta Requisiti per le etichette.
Ruoli IAM richiesti
Per ottenere l'autorizzazione necessaria per aggiungere un'etichetta a un set di dati esistente, chiedi all'amministratore di concederti il ruolo IAM Editor dati BigQuery (roles/bigquery.dataEditor
).
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene l'autorizzazione bigquery.datasets.update
, necessaria per aggiungere un'etichetta a un set di dati esistente.
Potresti riuscire a ottenere questa autorizzazione anche con i ruoli personalizzati o altri ruoli predefiniti.
Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Ruoli e autorizzazioni predefiniti.
Aggiunta di un'etichetta a un set di dati
Per aggiungere un'etichetta a un set di dati dopo la sua creazione:
Console
Nella console Google Cloud, seleziona il set di dati.
Nella pagina dei dettagli del set di dati, fai clic sull'icona a forma di matita a destra di Etichette.
Nella finestra di dialogo Modifica etichette:
- Fai clic su Aggiungi etichetta.
- Inserisci la chiave e il valore. Per applicare altre etichette, fai clic su Aggiungi etichetta. Ogni chiave può essere utilizzata solo una volta per set di dati, ma puoi utilizzare la stessa chiave in set di dati diversi dello stesso progetto.
- Per aggiornare un'etichetta, modifica le chiavi o i valori esistenti.
- Per salvare le modifiche, fai clic su Aggiorna.
SQL
Utilizza l'istruzione DDL ALTER SCHEMA SET OPTIONS
per impostare le etichette su un set di dati esistente. Le etichette delle impostazioni sovrascriveranno
tutte le etichette esistenti nel set di dati. L'esempio seguente imposta un'etichetta sul set di dati mydataset
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'editor query, inserisci la seguente istruzione:
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, vedi Eseguire una query interattiva.
bq
Per aggiungere un'etichetta a un set di dati esistente, esegui il comando bq update
con
il flag set_label
. Ripeti il flag per aggiungere più etichette.
Se il set di dati si trova in un progetto diverso da quello predefinito, aggiungi l'ID progetto al set di dati nel seguente formato: PROJECT_ID:DATASET
.
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
Sostituisci quanto segue:
KEY:VALUE
: una coppia chiave-valore per un'etichetta che vuoi aggiungere. La chiave deve essere univoca. Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti caratteri internazionali.PROJECT_ID
: il tuo ID progetto.DATASET
: il set di dati che stai etichettando.
Esempi:
Per aggiungere un'etichetta per monitorare i reparti, inserisci il comando bq update
e
specifica department
come chiave di etichetta. Ad esempio, per aggiungere
un'etichetta department:shipping
a mydataset
nel tuo progetto predefinito, inserisci:
bq update --set_label department:shipping mydataset
Per aggiungere più etichette a un set di dati, ripeti il flag set_label
e specifica una chiave univoca per ogni etichetta.Ad esempio, per aggiungere un'etichetta department:shipping
e un'etichetta cost_center:logistics
a mydataset
nel tuo progetto predefinito, inserisci:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
Per aggiungere un'etichetta a un set di dati esistente, chiama il metodo datasets.patch
e compila la proprietà labels
per la risorsa del set di dati.
Poiché il metodo datasets.update
sostituisce l'intera risorsa del set di dati,
è preferibile il metodo datasets.patch
.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
In questo esempio viene utilizzata la libreria client HTTP di Google per Java per inviare una richiesta all'API BigQuery.
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Aggiungere etichette a tabelle e viste
Un'etichetta può essere aggiunta a una tabella o a una visualizzazione quando viene creata:
- Utilizzo del comando
bq mk
dello strumento a riga di comando bq - Chiamata al metodo API
tables.insert
Questa pagina illustra come aggiungere un'etichetta a una tabella o a una visualizzazione esistente. Per scoprire di più sull'aggiunta di un'etichetta quando crei una tabella o una vista, consulta Creare una tabella o Creare una vista.
È possibile aggiungere un'etichetta dopo aver creato una tabella o una visualizzazione mediante:
- Utilizzo della console Google Cloud
- Utilizzo del comando
bq update
dello strumento a riga di comando bq - Chiamata al metodo API
tables.patch
- Utilizzo delle librerie client
Poiché le viste vengono trattate come risorse tabella, viene utilizzato il metodo tables.patch
per modificare sia le viste che le tabelle.
Ruoli IAM richiesti
Per ottenere le autorizzazioni necessarie per aggiungere un'etichetta a una tabella o vista esistente, chiedi all'amministratore di concederti il ruolo IAM Editor dati BigQuery (roles/bigquery.dataEditor
).
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per aggiungere un'etichetta a una tabella o una vista esistente. Per visualizzare esattamente le autorizzazioni necessarie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per aggiungere un'etichetta a una tabella o una vista esistente sono necessarie le seguenti autorizzazioni:
-
bigquery.tables.update
-
bigquery.tables.get
Potresti anche riuscire a ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.
Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Ruoli e autorizzazioni predefiniti.
Aggiungere un'etichetta a una tabella o una visualizzazione
Per aggiungere un'etichetta a una tabella o una visualizzazione esistente:
Console
Nella console Google Cloud, seleziona la tabella o visualizza.
Fai clic sulla scheda Dettagli.
Fai clic sull'icona a forma di matita a destra di Etichette.
Nella finestra di dialogo Modifica etichette:
- Fai clic su Aggiungi etichetta.
- Inserisci la chiave e il valore per aggiungere un'etichetta. Per applicare altre etichette, fai clic su Aggiungi etichetta. Ogni chiave può essere usata solo una volta per set di dati, ma puoi usare la stessa chiave in set di dati diversi dello stesso progetto.
- Modifica le chiavi o i valori esistenti per aggiornare un'etichetta.
- Fai clic su Update (Aggiorna) per salvare le modifiche.
SQL
Utilizza l'istruzione DDL ALTER TABLE SET OPTIONS
per impostare le etichette su una tabella esistente o l'istruzione DDL ALTER VIEW SET OPTIONS
per impostare le etichette su una vista esistente. Le etichette delle impostazioni sovrascriveranno
tutte le etichette esistenti nella tabella o nella vista. L'esempio seguente imposta due etichette nella tabella mytable
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'editor query, inserisci la seguente istruzione:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels = [('department', 'shipping'), ('cost_center', 'logistics')]);
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, vedi Eseguire una query interattiva.
bq
Per aggiungere un'etichetta a una tabella o una vista esistente, esegui il comando bq update
con il flag set_label
. Per aggiungere più etichette, ripeti il flag.
Se la tabella o la vista si trova in un progetto diverso da quello predefinito, aggiungi
l'ID progetto al set di dati nel seguente formato:
project_id:dataset
.
bq update \ --set_label KEY:VALUE \ PROJECT_ID:DATASET.TABLE_OR_VIEW
Sostituisci quanto segue:
KEY:VALUE
: una coppia chiave-valore per un'etichetta che vuoi aggiungere. La chiave deve essere univoca. Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti caratteri internazionali.PROJECT_ID
: il tuo ID progetto.DATASET
: il set di dati contenente la tabella o la vista che stai etichettando.TABLE_OR_VIEW
: il nome della tabella o della vista che stai etichettando.
Esempi:
Per aggiungere un'etichetta alla tabella che tenga traccia dei reparti, inserisci il comando bq update
e specifica department
come chiave di etichetta. Ad esempio, per aggiungere
un'etichetta department:shipping
a mytable
nel tuo progetto predefinito, inserisci:
bq update --set_label department:shipping mydataset.mytable
Per aggiungere un'etichetta di visualizzazione che tenga traccia dei reparti, inserisci il comando bq update
e specifica department
come chiave di etichetta. Ad esempio, per aggiungere
un'etichetta department:shipping
a myview
nel tuo progetto predefinito, inserisci:
bq update --set_label department:shipping mydataset.myview
Per aggiungere più etichette a una tabella o a una visualizzazione, ripeti il flag set_label
e specifica una chiave univoca per ogni etichetta. Ad esempio, per aggiungere un'etichetta department:shipping
e un'etichetta cost_center:logistics
a mytable
nel tuo progetto predefinito, inserisci:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset.mytable
API
Per aggiungere un'etichetta a una tabella o vista esistente, chiama il metodo tables.patch
e compila la proprietà labels
per la risorsa della tabella.
Poiché le viste vengono trattate come risorse tabella, viene utilizzato il metodo tables.patch
per modificare sia le viste che le tabelle.
Poiché il metodo tables.update
sostituisce l'intera risorsa del set di dati, è preferibile il metodo tables.patch
.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
In questo esempio viene utilizzata la libreria client HTTP di Google per Java per inviare una richiesta all'API BigQuery.
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Aggiunta di etichette ai job
Puoi aggiungere etichette ai job di query tramite la riga di comando utilizzando il flag --label
dello strumento a riga di comando bq. Lo strumento bq supporta l'aggiunta
di etichette solo ai job di query.
Puoi anche aggiungere un'etichetta a un job inviato tramite l'API specificando la proprietà labels
nella configurazione del job quando chiami il metodo jobs.insert
. L'API può essere utilizzata per aggiungere etichette a qualsiasi tipo di job.
Non puoi aggiungere etichette o aggiornare le etichette per job in attesa, in esecuzione o completati.
Quando aggiungi un'etichetta a un job, questa viene inclusa nei dati di fatturazione.
Ruoli IAM richiesti
Per ottenere l'autorizzazione necessaria per aggiungere un'etichetta a un job, chiedi all'amministratore di concederti il ruolo IAM Utente BigQuery (roles/bigquery.user
).
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene l'autorizzazione bigquery.jobs.create
, necessaria per aggiungere un'etichetta a un job.
Potresti riuscire a ottenere questa autorizzazione anche con i ruoli personalizzati o altri ruoli predefiniti.
Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Ruoli e autorizzazioni predefiniti.
Aggiunta di un'etichetta a un job
Per aggiungere un'etichetta a un job:
bq
Per aggiungere un'etichetta a un job di query, esegui il comando bq query
con
il flag --label
. Per aggiungere più etichette, ripeti il flag. Il flag --nouse_legacy_sql
indica che la query è in sintassi GoogleSQL.
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
Sostituisci quanto segue:
KEY:VALUE
: una coppia chiave-valore per un'etichetta che vuoi aggiungere al job di query. La chiave deve essere univoca. Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti caratteri internazionali. Per aggiungere più etichette a un job di query, ripeti il flag--label
e specifica una chiave univoca per ogni etichetta.QUERY
: una query GoogleSQL valida.
Esempi:
Per aggiungere un'etichetta a un job di query, inserisci:
bq query \
--label department:shipping \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
Per aggiungere più etichette a un job di query, ripeti il flag --label
e specifica una chiave univoca per ogni etichetta. Ad esempio, per aggiungere un'etichetta department:shipping
e un'etichetta cost_center:logistics
a un job di query, inserisci:
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
Per aggiungere un'etichetta a un job, chiama il metodo jobs.insert
e compila la proprietà labels
per la configurazione del job.
Puoi utilizzare l'API per aggiungere etichette a qualsiasi tipo di job.
Associare i job di una sessione a un'etichetta
Se esegui query in una sessione, puoi assegnare un'etichetta a tutti i job di query futuri nella sessione utilizzando le query con più istruzioni di BigQuery.
SQL
Imposta la variabile di sistema @@query_label
nella sessione eseguendo questa query:
SET @@query_label = "KEY:VALUE";
- KEY:VALUE: una coppia chiave-valore che l'etichetta deve assegnare a tutte le query future nella sessione. La chiave deve essere univoca. Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti caratteri internazionali.
Esempio:
SET @@query_label = "cost_center:logistics";
API
Per aggiungere un'etichetta a un job di query in una sessione quando
esegui una query utilizzando una chiamata API, chiama
il metodo jobs.insert
e compila la proprietà query_label
per la
connectionProperties
configurazione del job.
Dopo aver associato un'etichetta di query a una sessione ed eseguito query al suo interno, puoi raccogliere gli audit log per le query con quell'etichetta. Per ulteriori informazioni, consulta Riferimento degli audit log per BigQuery.
Aggiunta di un'etichetta senza un valore
Un'etichetta con una chiave con un valore vuoto a volte viene chiamata tag. Questo non deve essere confuso con una risorsa di tag. Per scoprire di più, consulta la sezione Etichette e tag. Puoi creare una nuova etichetta senza valore oppure puoi rimuovere un valore da una chiave di etichetta esistente.
Le etichette senza valori possono essere utili nelle situazioni in cui stai etichettando una risorsa, ma non hai bisogno del formato chiave-valore. Ad esempio, se una tabella contiene dati di test utilizzati da più gruppi, come assistenza o sviluppo, puoi aggiungere un'etichetta test_data
alla tabella per identificarli.
Per aggiungere un'etichetta senza un valore:
Console
Nella console Google Cloud, seleziona la risorsa appropriata (set di dati, tabella o vista).
Per i set di dati, viene aperta automaticamente la pagina dei dettagli del set di dati. Per tabelle e viste, fai clic su Dettagli per aprire la pagina dei dettagli.
Nella pagina dei dettagli, fai clic sull'icona a forma di matita a destra di Etichette.
Nella finestra di dialogo Modifica etichette:
- Fai clic su Aggiungi etichetta.
- Inserisci una nuova chiave e lascia vuoto il valore. Per applicare altre etichette, fai clic su Aggiungi etichetta e ripeti.
- Per salvare le modifiche, fai clic su Aggiorna.
SQL
Per aggiungere un'etichetta senza un valore, utilizza
l'istruzione DDL ALTER TABLE SET OPTIONS
:
Nella console Google Cloud, vai alla pagina BigQuery.
Nell'editor query, inserisci la seguente istruzione:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
Fai clic su
Esegui.
Per ulteriori informazioni su come eseguire le query, vedi Eseguire una query interattiva.
bq
Per aggiungere un'etichetta senza un valore a una risorsa esistente, utilizza il
comando bq update
con il
flag set_label
. Specifica la chiave, seguita da due punti, ma lascia il valore non specificato.
bq update --set_label KEY: RESOURCE_ID
Sostituisci quanto segue:
KEY:
: la chiave di etichetta che vuoi utilizzare.RESOURCE_ID
: nome valido per un set di dati, una tabella o una vista. Se la risorsa si trova in un progetto diverso da quello predefinito, aggiungi l'ID progetto nel seguente formato:PROJECT_ID:DATASET
.
Esempi:
Inserisci questo comando per creare un'etichetta test_data
per mydataset.mytable
. mydataset
è nel tuo progetto predefinito.
bq update --set_label test_data: mydataset
API
Chiama il metodo datasets.patch
o il metodo tables.patch
e aggiungi etichette con il valore impostato sulla stringa vuota (""
) nella
risorsa set di dati
o nella risorsa tabella.
Puoi rimuovere i valori dalle etichette esistenti sostituendo i valori con
la stringa vuota.
Poiché le viste vengono trattate come risorse tabella, viene utilizzato il metodo tables.patch
per modificare sia le viste che le tabelle. Inoltre, poiché il metodo tables.update
sostituisce l'intera risorsa del set di dati, è preferibile utilizzare il metodo tables.patch
.
Passaggi successivi
- Scopri come visualizzare le etichette nelle risorse BigQuery.
- Scopri come aggiornare le etichette nelle risorse BigQuery.
- Scopri come filtrare le risorse utilizzando le etichette.
- Scopri come eliminare le etichette dalle risorse BigQuery.
- Leggi ulteriori informazioni sull'utilizzo delle etichette nella documentazione di Resource Manager.