Aggiornamento etichette

Questa pagina spiega come aggiornare le etichette nelle risorse BigQuery.

Prima di iniziare

Concedi i ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento. Le autorizzazioni necessarie per eseguire un'attività (se presenti) sono elencate nella sezione "Autorizzazioni richieste" dell'attività.

Aggiornamento delle etichette dei set di dati

Un'etichetta del set di dati può essere aggiornata:

• Utilizzo della console Google Cloud
• Utilizzo di istruzioni DDL SQL
• Utilizzo del comando bq update dello strumento a riga di comando bq
• Chiamata del metodo dell'API datasets.patch
• Utilizzo delle librerie client

Autorizzazioni obbligatorie

Per aggiornare l'etichetta di un set di dati, devi disporre dell'autorizzazione IAM bigquery.datasets.update.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per aggiornare l'etichetta di un set di dati:

• roles/bigquery.dataOwner
• roles/bigquery.admin

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi aggiornare le etichette dei set di dati che crei.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Aggiornamento di un'etichetta del set di dati

Per aggiornare le etichette in un set di dati, seleziona una delle seguenti opzioni:

Console

1. Nella console Google Cloud, seleziona il set di dati.

2. Nella pagina dei dettagli del set di dati, fai clic sull'icona a forma di matita a destra di Etichette.

   

3. Nella finestra di dialogo Modifica etichette:

   • 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 diversi set di dati nello 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 SCHEMA SET OPTIONS per impostare le etichette su un set di dati esistente. L'impostazione delle etichette sovrascrive eventuali etichette esistenti nel set di dati. L'esempio seguente imposta una singola etichetta sul set di dati mydataset:

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

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   ALTER SCHEMA mydataset
   SET OPTIONS (labels = [('sensitivity', 'high')]);

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

Per aggiungere altre etichette o aggiornare un'etichetta del set di dati, esegui il comando bq update con il flag set_label. Ripeti il flag per aggiungere o aggiornare 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

Dove:

• key:value corrisponde a una coppia chiave:valore per un'etichetta che vuoi aggiungere o aggiornare. Se specifichi la stessa chiave di un'etichetta esistente, il valore dell'etichetta esistente viene aggiornato. La chiave deve essere univoca.
• project_id è l'ID progetto.
• dataset è il set di dati che stai aggiornando.

Esempio:

Per aggiornare l'etichetta department su mydataset, inserisci il comando bq update e specifica department come chiave dell'etichetta. Ad esempio, per aggiornare l'etichetta department:shipping in department:logistics, inserisci il comando seguente. mydataset si trova in myotherproject, non nel progetto predefinito.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

L'output è simile al seguente.

Dataset 'myotherproject:mydataset' successfully updated.

API

Per aggiungere altre etichette o aggiornare un'etichetta per un set di dati esistente, chiama il metodo datasets.patch e aggiungi o aggiorna la proprietà labels per la risorsa set di dati.

Poiché il metodo datasets.update sostituisce l'intera risorsa del set di dati, è preferibile il metodo datasets.patch.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione Go riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Questo esempio utilizza la libreria client HTTP di Google per Java per inviare una richiesta all'API BigQuery.

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Aggiornamento delle etichette di tabelle e viste

Un'etichetta può essere aggiornata dopo la creazione di una tabella o di una visualizzazione:

• Utilizzo della console Google Cloud
• Utilizzo del comando bq update dello strumento a riga di comando bq
• Chiamata del metodo API tables.patch
  • Poiché le visualizzazioni vengono trattate come risorse tabella, utilizza il tables.patch metodo per modificare sia le visualizzazioni sia le tabelle.
• Utilizzo delle librerie client

Autorizzazioni obbligatorie

Per aggiornare un'etichetta di tabella o vista, devi disporre dell'autorizzazione IAM bigquery.tables.update.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per aggiornare una tabella o visualizzare un'etichetta:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi aggiornare le etichette delle tabelle e delle visualizzazioni nei set di dati che crei.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Aggiornamento di un'etichetta di tabella o visualizzazione

Per aggiornare l'etichetta di una tabella o di una vista:

Console

1. Nella console Google Cloud, seleziona la tabella o la visualizzazione.

2. Fai clic sulla scheda Dettagli e poi sull'icona a forma di matita a destra di Etichette.

3. Nella finestra di dialogo Modifica etichette:

   • Per applicare altre etichette, fai clic su Aggiungi etichetta. Ogni chiave può essere utilizzata solo una volta per tabella o vista, ma puoi utilizzare la stessa chiave in tabelle o viste in set di dati diversi.
   • 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 in una tabella esistente o l'istruzione DDL ALTER VIEW SET OPTIONS per impostare le etichette in una vista esistente. L'impostazione delle etichette sovrascrive eventuali etichette esistenti nella tabella o nella visualizzazione. L'esempio seguente imposta due etichette sulla tabella mytable:

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

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   ALTER TABLE mydataset.mytable
   SET OPTIONS (
     labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

Per aggiungere altre etichette o per aggiornare un'etichetta di tabella o vista, esegui il comando bq update con il flag set_label. Ripeti il flag per aggiungere o aggiornare più etichette.

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

Dove:

• key:value corrisponde a una coppia chiave:valore per un'etichetta che vuoi aggiungere o aggiornare. Se specifichi la stessa chiave di un'etichetta esistente, il valore dell'etichetta esistente viene aggiornato. La chiave deve essere univoca.
• project_id è l'ID progetto.
• dataset è il set di dati contenente la tabella o la vista che stai aggiornando.
• table_or_view è il nome della tabella o della visualizzazione che stai aggiornando.

Esempio:

Per aggiornare l'etichetta department per mytable, inserisci il comando bq update e specifica department come chiave dell'etichetta. Ad esempio, per aggiornare l'etichetta department:shipping in department:logistics per mytable, inserisci il seguente comando. mytable si trova in myotherproject, non nel tuo progetto predefinito.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

L'output è il seguente:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Per aggiungere etichette o aggiornare un'etichetta per una tabella o una vista esistente, chiama il metodo tables.patch e aggiungi o aggiorna la proprietà labels per la risorsa tabella.

Poiché le visualizzazioni vengono trattate come risorse tabella, utilizza il tables.patch metodo per modificare sia le visualizzazioni sia le tabelle.

Poiché il metodo tables.update sostituisce l'intera risorsa del set di dati, è preferibile il metodo tables.patch.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione Go riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Questo esempio utilizza la libreria client HTTP di Google per Java per inviare una richiesta all'API BigQuery.

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

Aggiornamento delle etichette dei job

Al momento, l'aggiornamento di un'etichetta del job non è supportato. Per aggiornare l'etichetta di un job, invia nuovamente il job specificando una nuova etichetta.

Conversione delle etichette in tag

Un'etichetta con una chiave con un valore vuoto viene utilizzata come tag. Puoi creare una nuova etichetta senza valore oppure trasformare un'etichetta esistente in un tag in un set di dati, una tabella o una visualizzazione. Non puoi convertire un'etichetta di job in un tag.

I tag possono essere utili in situazioni in cui etichetti una risorsa, ma non hai bisogno del formato key:value. Ad esempio, se hai una tabella contenente dati di test utilizzati da più gruppi (assistenza, sviluppo e così via), puoi aggiungere un tag test_data alla tabella per identificarla.

Autorizzazioni obbligatorie

Per convertire un'etichetta in un tag, devi disporre delle seguenti autorizzazioni IAM:

• bigquery.datasets.update (consente di convertire un'etichetta del set di dati)
• bigquery.tables.update (consente di convertire un'etichetta di tabella o visualizzazione)

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per convertire un'etichetta del set di dati:

• roles/bigquery.dataOwner
• roles/bigquery.admin

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per convertire una tabella o un'etichetta di visualizzazione:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi aggiornare le etichette dei set di dati che crei, nonché le tabelle e le visualizzazioni al loro interno.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Conversione di un'etichetta in un tag

Per convertire un'etichetta in un tag:

Console

1. Nella console Google Cloud, seleziona il set di dati, la tabella o la visualizzazione.

2. Per i set di dati, viene aperta automaticamente la pagina dei dettagli del set di dati. Per le tabelle e le visualizzazioni, fai clic su Dettagli per aprire la pagina dei dettagli.

   

3. Nella pagina dei dettagli, fai clic sull'icona a forma di matita a destra di Etichette.

   

4. Nella finestra di dialogo Modifica etichette:

   • Elimina il valore di un'etichetta esistente.
   • Fai clic su Aggiorna.

bq

Per convertire un'etichetta in un tag, utilizza il comando bq update con il set_label flag. Specifica la chiave, seguita da due punti, ma lascia il valore non specificato. In questo modo, un'etichetta esistente viene aggiornata in un tag.

bq update \
--set_label key: \
resource_id

Dove:

• key: è la chiave dell'etichetta che vuoi aggiornare in un tag.
• resource_id è un 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 il seguente comando per modificare l'etichetta test_data:development esistente su mydataset in un tag. mydataset si trova in myotherproject, non nel tuo progetto predefinito.

bq update --set_label test_data: myotherproject:mydataset

L'output è il seguente:

Dataset 'myotherproject:mydataset' successfully updated.

API

Per trasformare un'etichetta esistente in un tag, chiama il metodo datasets.patch o il metodo tables.patch e sostituisci i valori dell'etichetta con la stringa vuota ("") nella risorsa set di dati o nella risorsa tabella.

Poiché le visualizzazioni vengono trattate come risorse tabella, utilizza il tables.patch metodo per modificare sia le visualizzazioni sia le tabelle. Inoltre, poiché il metodo tables.update sostituisce l'intera risorsa set di dati, il metodo tables.patch è preferito.

Passaggi successivi

• Scopri come aggiungere etichette alle risorse BigQuery.
• Scopri come visualizzare le etichette nelle risorse BigQuery.
• Scopri come filtrare le risorse utilizzando le etichette.
• Scopri come eliminare le etichette nelle risorse BigQuery.
• Scopri di più sull'utilizzo delle etichette nella documentazione di Resource Manager.