Filtrer des ressources à l'aide de libellés

Pour filtrer des ressources à l'aide de libellés, vous pouvez effectuer l'une des opérations suivantes :

  • Utilisez la barre de recherche de la console Google Cloud.
  • créer une spécification de filtre à utiliser avec l'API, l'outil de ligne de commande bq ou les bibliothèques clientes.

Limites

  • L'API, l'outil de ligne de commande bq et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.
  • Le filtrage des tâches par libellé n'est disponible dans aucun des outils BigQuery.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Autorisations requises

Pour filtrer des ressources à l'aide de libellés, vous devez pouvoir récupérer les métadonnées de ressource. Pour filtrer des ressources à l'aide de libellés, vous devez disposer des autorisations IAM suivantes :

  • bigquery.datasets.get (vous permet de filtrer les ensembles de données)
  • bigquery.tables.get (vous permet de filtrer des tables et des vues)

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour filtrer les ensembles de données :

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

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour filtrer les tables et les vues :

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

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez filtrer les ressources que vous créez.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Filtrer des ressources dans la console Google Cloud

Pour générer une liste filtrée de ressources, utilisez la console Google Cloud :

  1. Dans la console Google Cloud, accédez au volet Explorateur.

  2. Dans la barre de recherche, saisissez key ou key:value. Les résultats incluent les correspondances partielles.

    Par exemple, si vous souhaitez n'afficher que les ensembles de données qui possèdent le libellé department:shipping, vous pouvez saisir department ou department:shipping.

Filtrer des ensembles de données dans l'API ou l'outil de ligne de commande bq

Actuellement, l'API, l'outil de ligne de commande bq et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.

Pour filtrer des ensembles de données à l'aide de l'API, de l'outil bq ou des bibliothèques clientes, créez une spécification de filtre et utilisez-la :

  • en tant que paramètre de l'option --filter dans l'outil bq ;
  • en tant que valeur de la propriété filter dans la méthode datasets.list de l'API.

Limites applicables aux spécifications de filtre

Les spécifications de filtre sont soumises aux limites suivantes :

  • Le seul opérateur logique compatible est l'opérateur AND. Les comparaisons séparées par des espaces sont considérées comme possédant des opérateurs AND implicites.
  • Le seul champ actuellement disponible pour le filtrage est labels.key, où key correspond à un nom de libellé.
  • Le filtre peut comprendre jusqu'à dix expressions.
  • Le filtrage est sensible à la casse.
  • Actuellement, l'API, l'outil de ligne de commande bq et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.

Exemples de spécifications de filtre

Une spécification de filtre utilise la syntaxe suivante :

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

Remplacez l'élément suivant :

  • field est exprimé au format labels.key, où keycorrespond à une clé de libellé.
  • value est une valeur de libellé facultative.

Les exemples suivants expliquent comment générer des expressions de filtre.

Pour répertorier les ressources qui possèdent le libellé department:shipping, utilisez la spécification de filtre suivante :

labels.department:shipping

Pour répertorier les ensembles de données qui possèdent plusieurs libellés, séparez les paires key:value par un espace. L'espace est traité comme un opérateur logique AND. Par exemple, si vous souhaitez répertorier les ensembles de données qui possèdent les libellés department:shipping et location:usa, utilisez la spécification de filtre suivante :

labels.department:shipping labels.location:usa

Plutôt que d'utiliser une paire clé/valeur, vous pouvez créer un filtre ne contenant qu'une clé. La spécification de filtre suivante répertorie tous les ensembles de données possédant le libellé department, quelle que soit la valeur :

labels.department

Une alternative consiste à utiliser un astérisque pour représenter toutes les valeurs possibles associées à la clé department :

labels.department:*

Vous pouvez également utiliser des tags dans une spécification de filtre. Par exemple, si vous souhaitez répertorier les ressources qui possèdent le libellé department:shipping et le tag test_data, utilisez la spécification de filtre suivante :

labels.department:shipping labels.test_data

Filtrer des ensembles de données dans l'outil de ligne de commande bq et dans l'API

Pour filtrer des ensembles de données à l'aide de l'API, de l'outil de ligne de commande bq ou des bibliothèques clientes :

bq

Exécutez la commande bq ls avec l'option --filter. Si vous répertoriez des ensembles de données dans un projet autre que votre projet par défaut, spécifiez l'option --project_id.

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

Remplacez l'élément suivant :

  • filter_specification est une spécification de filtre valide.
  • project_id est l'ID de votre projet.

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping :

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

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping et le tag test_data.

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

Saisissez la commande suivante pour répertorier les ensembles de données de myotherproject qui possèdent le libellé department:shipping :

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

Le résultat de chacune de ces commandes ressemble à ce qui suit. 

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

API

Appelez la méthode API datasets.list et fournissez la spécification de filtre à l'aide de la propriété filter.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Go.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 


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

Étapes suivantes