Ressourcen mithilfe von Labels filtern

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

  • Über die Suchleiste in der 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.

Erforderliche Berechtigungen

Wenn Sie mithilfe von Labels Ressourcen filtern möchten, müssen Sie die Metadaten von Ressourcen abrufen können. Dafür benötigen Sie mindestens folgende Berechtigungen:

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

Die folgenden vordefinierten IAM-Rollen enthalten Berechtigungen vom Typ bigquery.datasets.get:

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

Die folgenden vordefinierten IAM-Rollen enthalten Berechtigungen vom Typ bigquery.tables.get:

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

Wenn ein Nutzer mit Berechtigungen vom Typ bigquery.datasets.create ein Dataset erstellt, hat er dafür außerdem Zugriff als bigquery.dataOwner. Die Berechtigung bigquery.dataOwner gibt dem Nutzer die Möglichkeit, die von ihm erstellten Ressourcen zu filtern.

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

Ressourcen in der Cloud Console filtern

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

Console

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

  2. Geben Sie in der Suchleiste Ihren Wert für key, für value oder für das key:value-Paar ein. Die Ergebnisse können auch teilweise Übereinstimmungen enthalten.

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

    • key-Wert: department
    • value: shipping
    • key:value-Paar: department:shipping

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 ausprobieren, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

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: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Java API.

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: Clientbibliotheken verwenden. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

// 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: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API.


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