A atualizar etiquetas

Esta página explica como atualizar etiquetas em recursos do BigQuery.

Antes de começar

Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento. As autorizações necessárias para realizar uma tarefa (se aplicável) estão listadas na secção "Autorizações necessárias" da tarefa.

Atualize as etiquetas do conjunto de dados

Uma etiqueta do conjunto de dados pode ser atualizada das seguintes formas:

• Usar a Google Cloud consola
• Usar declarações DDL de SQL
• Usar o comando bq update da ferramenta de linhas de comando bq
• Chamar o método da API datasets.patch
• Usar as bibliotecas de cliente

Autorizações necessárias

Para atualizar uma etiqueta de conjunto de dados, precisa da autorização de IAM bigquery.datasets.update.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para atualizar uma etiqueta de conjunto de dados:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode atualizar as etiquetas dos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Atualize uma etiqueta de conjunto de dados

Para atualizar as etiquetas num conjunto de dados, selecione uma das seguintes opções:

Consola

1. Na Google Cloud consola, selecione o conjunto de dados.

2. Na página de detalhes do conjunto de dados, clique no ícone de lápis à direita de Etiquetas.

   

3. Na caixa de diálogo Editar etiquetas:

   • Para aplicar etiquetas adicionais, clique em Adicionar etiqueta. Cada chave só pode ser usada uma vez por conjunto de dados, mas pode usar a mesma chave em diferentes conjuntos de dados no mesmo projeto.
   • Modifique as chaves ou os valores existentes para atualizar uma etiqueta.
   • Clique em Atualizar para guardar as alterações.

SQL

Use a ALTER SCHEMA SET OPTIONS declaração DDL para definir as etiquetas num conjunto de dados existente. A definição de etiquetas substitui todas as etiquetas existentes no conjunto de dados. O exemplo seguinte define uma única etiqueta no conjunto de dados mydataset:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

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

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Para adicionar etiquetas adicionais ou atualizar a etiqueta de um conjunto de dados, emita o comando bq update com a flag set_label. Repita a flag para adicionar ou atualizar várias etiquetas.

Se o conjunto de dados estiver num projeto diferente do projeto predefinido, adicione o ID do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

bq update \
--set_label key:value \
project_id:dataset

Onde:

• key:value corresponde a um par de chave:valor para uma etiqueta que quer adicionar ou atualizar. Se especificar a mesma chave que uma etiqueta existente, o valor da etiqueta existente é atualizado. A chave tem de ser exclusiva.
• project_id é o ID do seu projeto.
• dataset é o conjunto de dados que está a atualizar.

Exemplo:

Para atualizar a etiqueta department em mydataset, introduza o comando bq update e especifique department como a chave da etiqueta. Por exemplo, para atualizar a etiqueta department:shipping para department:logistics, introduza o seguinte comando. mydataset está em myotherproject e não no seu projeto predefinido.

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

O resultado tem o seguinte aspeto.

Dataset 'myotherproject:mydataset' successfully updated.

API

Para adicionar etiquetas adicionais ou atualizar uma etiqueta para um conjunto de dados existente, chame o método datasets.patch e adicione ou atualize a propriedade labels para o recurso dataset.

Uma vez que o método datasets.update substitui o recurso do conjunto de dados completo, é preferível usar o método datasets.patch.

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

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

Este exemplo usa a biblioteca cliente HTTP Google para Java para enviar um pedido à API BigQuery.

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

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

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

// 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

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

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))

Atualize a tabela e veja as etiquetas

Pode atualizar uma etiqueta depois de criar uma tabela ou uma vista:

• Usar a Google Cloud consola
• Usar o comando bq update da ferramenta de linhas de comando bq
• Chamar o método da API tables.patch
  • Uma vez que as vistas são tratadas como recursos de tabelas, usa o método tables.patch para modificar vistas e tabelas.
• Usar as bibliotecas de cliente

Autorizações necessárias

Para atualizar uma tabela ou uma etiqueta de visualização, precisa da autorização de IAM bigquery.tables.update.

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para atualizar uma tabela ou uma etiqueta de visualização:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode atualizar as etiquetas das tabelas e das vistas nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Atualize uma etiqueta de tabela ou vista

Para atualizar uma tabela ou uma etiqueta de visualização:

Consola

1. Na Google Cloud consola, selecione a tabela ou a vista.

2. Clique no separador Detalhes e, de seguida, clique no ícone de lápis à direita de Etiquetas.

3. Na caixa de diálogo Editar etiquetas:

   • Para aplicar etiquetas adicionais, clique em Adicionar etiqueta. Cada chave só pode ser usada uma vez por tabela ou vista, mas pode usar a mesma chave em tabelas ou vistas em diferentes conjuntos de dados.
   • Modifique as chaves ou os valores existentes para atualizar uma etiqueta.
   • Clique em Atualizar para guardar as alterações.

SQL

Use a ALTER TABLE SET OPTIONS declaração DDL para definir as etiquetas numa tabela existente ou a ALTER VIEW SET OPTIONS declaração DDL para definir as etiquetas numa vista existente. A definição de etiquetas substitui quaisquer etiquetas existentes na tabela ou na vista. O exemplo seguinte define duas etiquetas na tabela mytable:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

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

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Para adicionar etiquetas adicionais ou atualizar uma etiqueta de tabela ou visualização de propriedade, emita o comando bq update com a flag set_label. Repita a flag para adicionar ou atualizar várias etiquetas.

Se a tabela ou a vista estiver num projeto diferente do projeto predefinido, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

bq update \
--set_label key:value \
project_id:dataset.table_or_view

Onde:

• key:value corresponde a um par de chave:valor para uma etiqueta que quer adicionar ou atualizar. Se especificar a mesma chave que uma etiqueta existente, o valor da etiqueta existente é atualizado. A chave tem de ser exclusiva.
• project_id é o ID do seu projeto.
• dataset é o conjunto de dados que contém a tabela ou a vista que está a atualizar.
• table_or_view é o nome da tabela ou da vista que está a atualizar.

Exemplo:

Para atualizar a etiqueta department para mytable, introduza o comando bq update e especifique department como a chave da etiqueta. Por exemplo, para atualizar a etiqueta department:shipping para department:logistics para mytable, introduza o seguinte comando. mytable está em myotherproject e não no seu projeto predefinido.

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

O resultado tem o seguinte aspeto:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Para adicionar etiquetas ou atualizar uma etiqueta para uma tabela ou uma vista existente, chame o método tables.patch e adicione ou atualize a propriedade labels para o recurso de tabela.

Uma vez que as vistas são tratadas como recursos de tabelas, usa o método tables.patch para modificar vistas e tabelas.

Uma vez que o método tables.update substitui todo o recurso do conjunto de dados, o método tables.patch é preferível.

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

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

Este exemplo usa a biblioteca cliente HTTP Google para Java para enviar um pedido à API BigQuery.

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

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

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

// 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

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

# 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

Atualize as etiquetas de tarefas

A atualização de uma etiqueta de tarefa não é suportada. Para atualizar a etiqueta de uma tarefa, reenvie a tarefa com uma nova etiqueta especificada.

Atualize as etiquetas de reserva

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode atualizar uma etiqueta numa reserva. A atualização de uma etiqueta através de SQL substitui quaisquer etiquetas existentes na reserva.

Funções de IAM necessárias

Para receber a autorização de que precisa para atualizar uma etiqueta para uma reserva, peça ao seu administrador para lhe conceder a função do IAM Editor de recursos do BigQuery (roles/bigquery.resourceEditor) no projeto de administração. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém a autorização bigquery.reservations.update , que é necessária para atualizar uma etiqueta para uma reserva.

Também pode obter esta autorização com funções personalizadas ou outras funções predefinidas.

Atualize uma etiqueta numa reserva

Para atualizar uma etiqueta de uma reserva:

bq

Para atualizar uma etiqueta para uma reserva, execute o comando bq update com o indicador set_label e o indicador --reservation. Para atualizar várias etiquetas, repita a flag.

bq update --set_label KEY:VALUE  --reservation RESERVATION_NAME

Substitua o seguinte:

• KEY:VALUE: um par chave-valor para uma etiqueta que quer atualizar na reserva. A chave tem de ser exclusiva. As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais. Para atualizar várias etiquetas numa reserva, repita a flag --label e especifique uma chave exclusiva para cada etiqueta.
• RESERVATION_NAME: o nome da reserva.

SQL

Para atualizar uma etiqueta para uma reserva, use a declaração ALTER RESERVATION SET OPTIONSDDL para definir as etiquetas numa reserva existente. A definição de etiquetas substitui quaisquer etiquetas existentes na reserva. O exemplo seguinte define uma etiqueta na reserva myreservation:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

   ALTER RESERVATION myreservation
   SET OPTIONS (
     labels = [('sensitivity', 'high')]);

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

Converta etiquetas em marcadores

Uma etiqueta que tem uma chave com um valor vazio é usada como uma etiqueta. Pode criar uma nova etiqueta sem valor ou transformar uma etiqueta existente numa etiqueta num conjunto de dados, numa tabela ou numa vista. Não pode converter uma etiqueta de trabalho numa etiqueta.

As etiquetas podem ser úteis em situações em que está a etiquetar um recurso, mas não precisa do formato key:value. Por exemplo, se tiver uma tabela que contenha dados de teste usados por vários grupos (apoio técnico, desenvolvimento, etc.), pode adicionar uma etiqueta test_data à tabela para a identificar.

Autorizações necessárias

Para converter uma etiqueta numa etiqueta, precisa das seguintes autorizações de IAM:

• bigquery.datasets.update (permite converter uma etiqueta de conjunto de dados)
• bigquery.tables.update (permite-lhe converter uma tabela ou uma etiqueta View)

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para converter uma etiqueta de conjunto de dados:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para converter uma tabela ou uma etiqueta de visualização:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode atualizar as etiquetas dos conjuntos de dados que criar e das tabelas e vistas nesses conjuntos de dados.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Converta um marcador numa etiqueta

Para converter uma etiqueta numa etiqueta:

Consola

1. Na Google Cloud consola, selecione o conjunto de dados, a tabela ou a vista.

2. Para conjuntos de dados, a página de detalhes do conjunto de dados é aberta automaticamente. Para tabelas e vistas, clique em Detalhes para abrir a página de detalhes.

   

3. Na página de detalhes, clique no ícone de lápis à direita de Etiquetas.

   

4. Na caixa de diálogo Editar etiquetas:

   • Elimine o valor de uma etiqueta existente.
   • Clique em Atualizar.

bq

Para converter uma etiqueta num marcador, use o comando bq update com a flag set_label. Especifique a chave, seguida de dois pontos, mas deixe o valor não especificado. Isto atualiza uma etiqueta existente para uma etiqueta.

bq update \
--set_label key: \
resource_id

Onde:

• key: é a chave da etiqueta que quer atualizar para uma etiqueta.
• resource_id é um nome de conjunto de dados, tabela ou vista válido. Se o recurso estiver num projeto diferente do seu projeto predefinido, adicione o ID do projeto no seguinte formato: project_id:dataset.

Exemplos:

Introduza o seguinte comando para alterar a etiqueta test_data:development existente em mydataset para uma etiqueta. mydataset está em myotherproject e não no seu projeto predefinido.

bq update --set_label test_data: myotherproject:mydataset

O resultado tem o seguinte aspeto:

Dataset 'myotherproject:mydataset' successfully updated.

API

Para transformar uma etiqueta existente numa etiqueta, chame o método datasets.patch ou o método tables.patch e substitua os valores da etiqueta pela string vazia ("") no recurso dataset ou no recurso table.

Uma vez que as vistas são tratadas como recursos de tabelas, usa o método tables.patch para modificar vistas e tabelas. Além disso, uma vez que o método tables.update substitui todo o recurso do conjunto de dados, o método tables.patch é preferível.

O que se segue?

• Saiba como adicionar etiquetas aos recursos do BigQuery.
• Saiba como ver etiquetas em recursos do BigQuery.
• Saiba como filtrar recursos através de etiquetas.
• Saiba como eliminar etiquetas em recursos do BigQuery.
• Leia acerca da utilização de etiquetas na documentação do Resource Manager.