Ressourcen mithilfe von Labels filtern

Sie haben folgende Möglichkeiten, Ressourcen mithilfe von Labels zu filtern:

  • Verwendung der Suchleiste in der Google Cloud Console
  • Durch Erstellen einer Filterspezifikation zur Verwendung in der API, im bq-Befehlszeilentool oder in den Clientbibliotheken

Beschränkungen

  • Die API, das bq-Befehlszeilentool und die Clientbibliotheken unterstützen derzeit nur das Filtern von Datasets.
  • In keinem BigQuery-Tool können derzeit Jobs nach Label gefiltert werden.

Hinweis

Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.

Erforderliche Berechtigungen

Wenn Sie mithilfe von Labels Ressourcen filtern möchten, müssen Sie die Metadaten von Ressourcen abrufen können. Zum Filtern von Ressourcen mithilfe von Labels benötigen Sie die folgenden IAM-Berechtigungen:

  • bigquery.datasets.get (zum Filtern von Datasets)
  • bigquery.tables.get (zum Filtern von Tabellen und Ansichten)

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie zum Filtern von Datasets benötigen:

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

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie zum Filtern von Tabellen und Ansichten benötigen:

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

Wenn Sie die Berechtigung bigquery.datasets.create haben, können Sie auch die von Ihnen erstellten Ressourcen filtern.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Ressourcen in der Google Cloud Console filtern

Verwenden Sie die Google Cloud Console, um eine gefilterte Liste von Ressourcen zu generieren:

  1. Wechseln Sie in der Google Cloud Console zum Bereich Explorer.

  2. Geben Sie in der Suchleiste das Paar key oder key:value ein. Die Ergebnisse enthalten auch teilweise Übereinstimmungen.

    Wenn Sie beispielsweise nur Datasets mit dem Label department:shipping anzeigen lassen möchten, geben Sie department oder department:shipping ein.

Datasets mit der API oder mit dem bq-Befehlszeilentool filtern

Die API, das bq-Befehlszeilentool und die Clientbibliotheken unterstützen derzeit nur das Filtern von Datasets.

Um Datasets mithilfe der API, des bq-Tools oder der Clientbibliotheken zu filtern, erstellen Sie eine Filterspezifikation und verwenden diese als:

  • Parameter für das Flag --filter im bq-Tool
  • Wert für das Attribut filter in der Methode datasets.list der API

Einschränkungen bei Filterspezifikationen

Filterspezifikationen unterliegen den folgenden Einschränkungen:

  • Es wird nur der logische Operator AND unterstützt. Durch Leerzeichen getrennte Vergleiche werden behandelt, als enthielten sie implizite AND-Operatoren.
  • Als einziges Feld für die Filterung ist derzeit labels.key verfügbar, wobei key der Name eines Labels ist.
  • Der Filter kann bis zu zehn Ausdrücke enthalten.
  • Beim Filtern wird zwischen Groß- und Kleinschreibung unterschieden.
  • Die API, das bq-Befehlszeilentool und die Clientbibliotheken unterstützen derzeit nur das Filtern von Datasets.

Beispiele für Filterspezifikationen

Eine Filterspezifikation hat folgende Syntax:

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

Dabei gilt:

  • field wird als labels.key ausgedrückt, wobei key ein Labelschlüssel ist.
  • value ist ein optionaler Labelwert.

Die folgenden Beispiele zeigen, wie Filterausdrücke generiert werden.

Zur Auflistung von Ressourcen mit dem Label department:shipping verwenden Sie folgende Filterspezifikation:

labels.department:shipping

Zur Auflistung von Ressourcen mit mehreren Labels müssen Sie die key:value-Paare durch ein Leerzeichen trennen. Das Leerzeichen wird wie ein logischer AND-Operator behandelt. Wenn Sie beispielsweise Datasets mit dem Label department:shipping und dem Label location:usa auflisten möchten, verwenden Sie folgende Filterspezifikation:

labels.department:shipping labels.location:usa

Sie können auch nur nach dem Vorhandensein eines Schlüssels filtern und nicht nach einem Schlüssel/Wert-Paar. Die folgende Filterspezifikation listet unabhängig vom Wert alle Datasets mit dem Label department auf.

labels.department

In einer vergleichbaren Filterspezifikation werden mit einem Sternchen alle möglichen Werte dargestellt, die dem Schlüssel department zugeordnet sind:

labels.department:*

Sie können in einer Filterspezifikation auch Tags verwenden. Wenn Sie beispielsweise Ressourcen mit dem Label department:shipping und dem Tag test_data auflisten möchten, verwenden Sie folgende Filterspezifikation:

labels.department:shipping labels.test_data

Datasets mit dem bq-Befehlszeilentool und mit der API filtern

So filtern Sie Datasets mithilfe der API, des bq-Befehlszeilentools oder mit Clientbibliotheken:

bq

Führen Sie den Befehl bq ls mit dem Flag --filter aus. Wenn Sie Datasets in einem anderen Projekt als in Ihrem Standardprojekt auflisten möchten, geben Sie das Flag --project_id an.

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

Dabei gilt:

  • filter_specification ist eine gültige Filterspezifikation.
  • project_id ist die Projekt-ID.

Beispiele:

Mit dem folgenden Befehl können Sie Datasets mit dem Label department:shipping in Ihrem Standardprojekt auflisten:

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

Mit dem folgenden Befehl listen Sie alle Datasets mit dem Label department:shipping und mit dem Tag test_data in Ihrem Standardprojekt auf.

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

Mit dem folgenden Befehl listen Sie alle Datasets in myotherproject mit dem Label department:shipping auf:

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

Die Ausgabe für jeden dieser Befehle ist eine Liste von Datasets wie die im Folgenden aufgeführte Liste. 

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

API

Rufen Sie die API-Methode datasets.list auf und geben Sie die Filterspezifikation mithilfe des Attributs filter an.

Go

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 


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

Nächste Schritte