Filtrer des ressources à l'aide d'étiquettes

Cette page explique comment filtrer vos ressources BigQuery à l'aide d'étiquettes.

Présentation

Pour filtrer des ressources à l'aide d'étiquettes, vous pouvez :

  • utiliser la barre de recherche de la console GCP ou de l'UI Web classique ;
  • créer une spécification de filtre à utiliser avec la CLI, l'API ou les bibliothèques clientes.

Limites

Voici les limites actuelles concernant le filtrage des ressources :

  • L'API, la CLI et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.
  • Le filtrage des tâches par étiquette n'est disponible dans aucun des outils BigQuery.

Autorisations requises

Pour filtrer des ressources à l'aide d'étiquettes, vous devez pouvoir récupérer les métadonnées de ressource. Pour effectuer cette opération, vous devez disposer au minimum des autorisations suivantes :

  • bigquery.datasets.get pour filtrer les ensembles de données
  • bigquery.tables.get pour filtrer les tables et les vues

Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.datasets.get :

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

Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.tables.get :

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

En outre, si un utilisateur dispose des autorisations bigquery.datasets.create, lorsqu'il crée un ensemble de données, il obtient également le rôle bigquery.dataOwner qui lui permet d'y accéder. L'accès bigquery.dataOwner donne à l'utilisateur la possibilité de filtrer les ressources qu'il crée.

Pour en savoir plus sur les rôles et les autorisations Cloud IAM dans BigQuery, consultez la page Contrôle des accès.

Filtrer des ressources dans l'interface utilisateur

Pour générer une liste filtrée de ressources à l'aide de la console GCP ou de l'interface utilisateur Web classique, procédez comme suit :

Console

  1. Dans le volet de navigation, développez la section Ressources.

  2. Dans la barre de recherche, saisissez l'élément key, l'élément value ou la paire 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 l'étiquette department:shipping, vous pouvez saisir les éléments suivants :

    • key : department
    • value : shipping
    • Paire key:value : department:shipping

UI classique

  1. Dans le volet de navigation, faites défiler l'écran jusqu'à la zone Filtrer par ID ou par étiquette. Cette zone s'affiche juste au-dessus de la liste de vos projets.

  2. Dans la barre de recherche, saisissez la clé, la valeur ou la paire clé/valeur. La paire clé/valeur doit être renseignée au format suivant : 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 l'étiquette department:shipping, vous pouvez saisir les éléments suivants :

    • key : department
    • value : shipping
    • Paire key:value : department:shipping

Filtrer des ensembles de données à l'aide de la CLI ou de l'API

À l'heure actuelle, l'API, la CLI 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 la CLI, de l'API ou des bibliothèques clientes, créez une spécification de filtre et utilisez-la :

  • en tant que paramètre de l'indicateur --filter dans la CLI ;
  • 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 traitées comme possédant des opérateurs AND implicites.
  • Le seul champ actuellement disponible pour le filtrage est le champ labels.key, où key correspond à un nom d'étiquette.
  • Le filtre peut comprendre jusqu'à dix expressions.
  • Le filtrage est sensible à la casse.
  • À l'heure actuelle, la CLI, l'API 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]..."

Où :

  • field est exprimé au format labels.key, où clé correspond à une clé d'étiquette.
  • value est une valeur d'étiquette facultative.

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

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

labels.department:shipping

Pour répertorier les ressources qui possèdent plusieurs étiquettes, séparez les paires key:value par une espace. L'espace est traitée comme un opérateur logique AND. Si vous souhaitez par exemple répertorier les ensembles de données qui possèdent les étiquettes 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 l'étiquette 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 l'étiquette 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 à l'aide de la CLI et de l'API

Pour filtrer des ensembles de données à l'aide de la CLI, de l'API ou des bibliothèques clientes, procédez comme suit :

CLI

Exécutez la commande bq ls en spécifiant l'indicateur --filter. Si vous répertoriez des ensembles de données dans un projet autre que celui par défaut, spécifiez le paramètre --project_id.

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

Où :

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

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent l'étiquette 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 l'étiquette 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 du projet myotherproject qui possèdent l'étiquette 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 incluez la spécification de filtre à l'aide de la propriété filter.

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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)
}

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

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

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.