Filtrar recursos com etiquetas

Para filtrar recursos através de etiquetas, pode fazer uma das seguintes ações:

  • Use a barra de pesquisa na Google Cloud consola.
  • Crie uma especificação de filtro para utilização na API, na ferramenta de linhas de comando bq ou nas bibliotecas cliente.

Limitações

  • A API, a ferramenta de linhas de comando bq e as bibliotecas de clientes suportam a filtragem apenas para conjuntos de dados.
  • Não pode filtrar tarefas por etiqueta em nenhuma das ferramentas 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.

Autorizações necessárias

Para filtrar recursos através de etiquetas, tem de conseguir obter os metadados dos recursos. Para filtrar recursos através de etiquetas, precisa das seguintes autorizações de IAM:

  • bigquery.datasets.get (permite-lhe filtrar conjuntos de dados)
  • bigquery.tables.get (permite-lhe filtrar tabelas e vistas)

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para filtrar conjuntos de dados:

  • roles/bigquery.user
  • roles/bigquery.metadataViewer
  • roles/bigquery.dataViewer
  • roles/bigquery.dataOwner
  • roles/bigquery.dataEditor
  • roles/bigquery.admin

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para filtrar tabelas e vistas:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode filtrar os recursos que cria.

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.

Filtre recursos na Google Cloud consola

Para gerar uma lista filtrada de recursos, use a Google Cloud consola:

  1. Na Google Cloud consola, aceda ao painel Explorador.

  2. Na barra de pesquisa, introduza o par key ou key:value. Os seus resultados incluem correspondências parciais.

    Por exemplo, para mostrar apenas conjuntos de dados com a etiqueta department:shipping, pode introduzir department ou department:shipping.

Filtre conjuntos de dados na API ou na ferramenta de linhas de comando bq

A API, a ferramenta de linhas de comando bq e as bibliotecas de clientes suportam a filtragem apenas para conjuntos de dados.

Para filtrar conjuntos de dados através da API, da ferramenta bq ou das bibliotecas de clientes, crie uma especificação de filtro e use-a:

  • Como parâmetro da flag --filter na ferramenta bq
  • Como o valor da propriedade filter no método datasets.list da API

Limitações nas especificações de filtros

As especificações de filtros têm as seguintes limitações:

  • Apenas o operador lógico AND é suportado. As comparações separadas por espaços são tratadas como tendo operadores AND implícitos.
  • O único campo elegível para filtragem é labels.key, em que key é o nome de uma etiqueta.
  • Cada key numa expressão de filtragem tem de ser exclusivo.
  • O filtro pode incluir até dez expressões.
  • A filtragem é sensível a maiúsculas e minúsculas.
  • A API, a ferramenta de linhas de comando bq e as bibliotecas de clientes suportam a filtragem apenas para conjuntos de dados.

Exemplos de especificação de filtros

Uma especificação de filtro usa a seguinte sintaxe:

"field[:value][ field[:value]]..."

Substitua o seguinte:

  • field é expresso como labels.key, onde key é uma chave de etiqueta.
  • value é um valor de etiqueta opcional.

Os exemplos seguintes mostram como gerar expressões de filtro.

Para listar recursos que tenham uma etiqueta department:shipping, use a seguinte especificação de filtro:

labels.department:shipping

Para listar recursos com várias etiquetas, separe os pares key:value com um espaço. O espaço é tratado como um operador lógico AND. Por exemplo, para listar conjuntos de dados com a etiqueta department:shipping e a etiqueta location:usa, use a seguinte especificação de filtro:

labels.department:shipping labels.location:usa

Pode filtrar pela presença de uma chave apenas, em vez de fazer a correspondência com um par chave:valor. A especificação de filtro seguinte apresenta todos os conjuntos de dados etiquetados como department, independentemente do valor.

labels.department

Uma especificação de filtro equivalente usa um asterisco para representar todos os valores possíveis associados à chave department.

labels.department:*

Também pode usar etiquetas numa especificação de filtro. Por exemplo, para listar recursos com a etiqueta department:shipping e a etiqueta test_data, use a seguinte especificação de filtro:

labels.department:shipping labels.test_data

Filtrar conjuntos de dados na ferramenta de linhas de comando bq e na API

Para filtrar conjuntos de dados através da API, da ferramenta de linhas de comando bq ou das bibliotecas de clientes:

bq

Emita o comando bq ls com a flag --filter. Se estiver a apresentar conjuntos de dados num projeto que não seja o projeto predefinido, especifique a flag --project_id.

bq ls \
--filter "filter_specification" \
--project_id project_id

Substitua o seguinte:

  • filter_specification é uma especificação de filtro válida.
  • project_id é o ID do seu projeto.

Exemplos:

Introduza o seguinte comando para listar os conjuntos de dados no seu projeto predefinido que têm uma etiqueta department:shipping:

bq ls --filter "labels.department:shipping"

Introduza o seguinte comando para listar os conjuntos de dados no seu projeto predefinido que têm uma etiqueta department:shipping e uma etiqueta test_data.

bq ls --filter "labels.department:shipping labels.test_data"

Introduza o seguinte comando para listar conjuntos de dados em myotherproject que tenham uma etiqueta department:shipping:

bq ls --filter "labels.department:shipping" --project_id myotherproject

O resultado de cada um destes comandos devolve uma lista de conjuntos de dados semelhante à seguinte. 

+-----------+
| datasetId |
+-----------+
| mydataset |
| mydataset2|
+-----------+

API

Chame o método da API datasets.list e forneça a especificação do filtro através da propriedade filter.

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"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listDatasetsByLabel demonstrates walking the collection of datasets in a project, and
// filtering that list to a subset that has specific label metadata.
func listDatasetsByLabel(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	it := client.Datasets(ctx)
	it.Filter = "labels.color:green"
	for {
		dataset, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
	}
	return nil
}

Java

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.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get list of datasets by label
public class ListDatasetsByLabel {

  public static void runListDatasetsByLabel() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String filter = "MY_LABEL_FILTER";
    listDatasetsByLabel(projectId, filter);
  }

  public static void listDatasetsByLabel(String projectId, String filter) {
    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();

      Page<Dataset> datasets =
          bigquery.listDatasets(
              projectId,
              BigQuery.DatasetListOption.pageSize(100),
              BigQuery.DatasetListOption.labelFilter(filter)); // "labels.color:green"
      if (datasets == null) {
        System.out.println("Dataset does not contain any models");
        return;
      }
      datasets
          .iterateAll()
          .forEach(
              dataset -> System.out.printf("Success! Dataset ID: %s ", dataset.getDatasetId()));
    } catch (BigQueryException e) {
      System.out.println("Project does not contain any datasets \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 listDatasetsByLabel() {
  // Lists all datasets in current GCP project, filtering by label color:green.

  const options = {
    filter: 'labels.color:green',
  };
  // Lists all datasets in the specified project
  const [datasets] = await bigquery.getDatasets(options);

  console.log('Datasets:');
  datasets.forEach(dataset => console.log(dataset.id));
}

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

label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))  # Make an API request.

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:
        print("\t{}.{}".format(dataset.project, dataset.dataset_id))
else:
    print("No datasets found with this filter.")

O que se segue?