Filtrar recursos con etiquetas

Para filtrar recursos mediante etiquetas, puede hacer lo siguiente:

  • Usa la barra de búsqueda de la Google Cloud consola.
  • Crea una especificación de filtro para usarla en la API, la herramienta de línea de comandos bq o las bibliotecas de cliente.

Limitaciones

  • La API, la herramienta de línea de comandos bq y las bibliotecas cliente solo admiten el filtrado de conjuntos de datos.
  • No puedes filtrar tareas por etiqueta en ninguna de las herramientas de BigQuery.

Antes de empezar

Concede roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos obligatorios

Para filtrar recursos mediante etiquetas, debe poder recuperar los metadatos de los recursos. Para filtrar recursos mediante etiquetas, necesitas los siguientes permisos de gestión de identidades y accesos:

  • bigquery.datasets.get (permite filtrar conjuntos de datos)
  • bigquery.tables.get (permite filtrar tablas y vistas)

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para filtrar conjuntos de datos:

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

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para filtrar tablas y vistas:

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

Además, si tienes el permiso bigquery.datasets.create, puedes filtrar los recursos que crees.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Filtrar recursos en la Google Cloud consola

Para generar una lista filtrada de recursos, usa la Google Cloud consola:

  1. En la Google Cloud consola, ve al panel Explorador.

  2. En la barra de búsqueda, introduce el par key o key:value. Los resultados incluyen las coincidencias parciales.

    Por ejemplo, para mostrar solo los conjuntos de datos con la etiqueta department:shipping, puede introducir department o department:shipping.

Filtrar conjuntos de datos en la API o en la herramienta de línea de comandos bq

La API, la herramienta de línea de comandos bq y las bibliotecas de cliente solo admiten el filtrado de conjuntos de datos.

Para filtrar conjuntos de datos mediante la API, la herramienta bq o las bibliotecas de cliente, crea una especificación de filtro y úsala:

  • Como parámetro de la marca --filter en la herramienta bq
  • Como valor de la propiedad filter en el método datasets.list de la API

Limitaciones de las especificaciones de filtros

Las especificaciones de los filtros tienen las siguientes limitaciones:

  • Solo se admite el operador lógico AND. Las comparaciones separadas por espacios se tratan como si tuvieran operadores AND implícitos.
  • El único campo apto para el filtrado es labels.key, donde key es el nombre de una etiqueta.
  • Cada key de una expresión de filtrado debe ser único.
  • El filtro puede incluir hasta diez expresiones.
  • El filtrado distingue entre mayúsculas y minúsculas.
  • La API, la herramienta de línea de comandos bq y las bibliotecas de cliente solo admiten el filtrado de conjuntos de datos.

Ejemplos de especificaciones de filtros

Una especificación de filtro utiliza la siguiente sintaxis:

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

Haz los cambios siguientes:

  • field se expresa como labels.key, donde key es una clave de etiqueta.
  • value es un valor de etiqueta opcional.

En los siguientes ejemplos se muestra cómo generar expresiones de filtro.

Para enumerar los recursos que tienen la etiqueta department:shipping, usa la siguiente especificación de filtro:

labels.department:shipping

Para enumerar recursos con varias etiquetas, separa los pares key:value con un espacio. El espacio se trata como un operador lógico AND. Por ejemplo, para enumerar los conjuntos de datos con las etiquetas department:shipping y location:usa, usa la siguiente especificación de filtro:

labels.department:shipping labels.location:usa

Puede filtrar por la presencia de una clave, en lugar de buscar coincidencias con un par clave-valor. La siguiente especificación de filtro muestra todos los conjuntos de datos etiquetados como department, independientemente del valor.

labels.department

Una especificación de filtro equivalente usa un asterisco para representar todos los valores posibles asociados a la clave department.

labels.department:*

También puedes usar etiquetas en una especificación de filtro. Por ejemplo, para enumerar los recursos con la etiqueta department:shipping y la etiqueta test_data, usa la siguiente especificación de filtro:

labels.department:shipping labels.test_data

Filtrar conjuntos de datos en la herramienta de línea de comandos bq y en la API

Para filtrar conjuntos de datos mediante la API, la herramienta de línea de comandos bq o las bibliotecas de cliente, sigue estos pasos:

bq

Ejecuta el comando bq ls con la marca --filter. Si vas a enumerar conjuntos de datos de un proyecto que no sea el predeterminado, especifica la marca --project_id.

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

Haz los cambios siguientes:

  • filter_specification es una especificación de filtro válida.
  • project_id es el ID del proyecto.

Ejemplos:

Introduce el siguiente comando para ver una lista de los conjuntos de datos de tu proyecto predeterminado que tengan la etiqueta department:shipping:

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

Introduce el siguiente comando para ver una lista de los conjuntos de datos de tu proyecto predeterminado que tengan la etiqueta department:shipping y la etiqueta test_data.

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

Introduce el siguiente comando para enumerar los conjuntos de datos de myotherproject que tengan la etiqueta department:shipping:

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

La salida de cada uno de estos comandos devuelve una lista de conjuntos de datos como la siguiente. 

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

API

Llama al método de API datasets.list y proporciona la especificación del filtro mediante la propiedad filter.

Go

Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación 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 probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación 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 probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación 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 probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación 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.")

Siguientes pasos