Filtrare le risorse utilizzando le etichette

Per filtrare le risorse utilizzando le etichette, puoi eseguire una delle seguenti operazioni:

  • Utilizzare la barra di ricerca nella Google Cloud console.
  • Creare una specifica di filtro da utilizzare nell'API, nello strumento a riga di comando bq o nelle librerie client.

Limitazioni

  • L'API, lo strumento a riga di comando bq e le librerie client supportano il filtro solo per i set di dati.
  • Non puoi filtrare i job per etichetta in nessuno degli strumenti BigQuery.

Prima di iniziare

Concedi i ruoli Identity and Access Management (IAM) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività descritta in questo documento.

Autorizzazioni obbligatorie

Per filtrare le risorse utilizzando le etichette, devi essere in grado di recuperare i metadati delle risorse. Per filtrare le risorse utilizzando le etichette, devi disporre delle seguenti autorizzazioni IAM:

  • bigquery.datasets.get (consente di filtrare i set di dati)
  • bigquery.tables.get (consente di filtrare tabelle e visualizzazioni)

Ognuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per filtrare i set di dati:

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

Ognuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per filtrare tabelle e visualizzazioni:

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

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi filtrare le risorse che crei.

Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Filtrare le risorse nella Google Cloud console

Per generare un elenco filtrato di risorse, utilizza la Google Cloud console:

  1. Nella Google Cloud console, vai al riquadro Explorer.

  2. Nella barra di ricerca, inserisci la coppia key o key:value. I risultati includono eventuali corrispondenze parziali.

    Ad esempio, per mostrare solo i set di dati con l'etichetta department:shipping, puoi inserire department o department:shipping.

Filtrare i set di dati nell'API o nello strumento a riga di comando bq

L'API, lo strumento a riga di comando bq e le librerie client supportano il filtro solo per i set di dati.

Per filtrare i set di dati utilizzando l'API, lo strumento bq o le librerie client, crea una specifica di filtro e utilizzala:

  • Come parametro per il flag --filter nello strumento bq
  • Come valore per la proprietà filter nel metodo datasets.list dell'API

Limitazioni delle specifiche di filtro

Le specifiche di filtro presentano le seguenti limitazioni:

  • È supportato solo l'operatore logico AND. I confronti separati da spazi vengono trattati come se avessero operatori AND impliciti.
  • L'unico campo idoneo per il filtro è labels.key, dove key è il nome di un'etichetta.
  • Ogni key in un'espressione di filtro deve essere univoca.
  • Il filtro può includere fino a dieci espressioni.
  • Il filtro fa distinzione tra maiuscole e minuscole.
  • L'API, lo strumento a riga di comando bq e le librerie client supportano il filtro solo per i set di dati.

Esempi di specifiche di filtro

Una specifica di filtro utilizza la seguente sintassi:

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

Sostituisci quanto segue:

  • field viene espresso come labels.key, dove key è una chiave di etichetta.
  • value è un valore di etichetta facoltativo.

Gli esempi riportati di seguito mostrano come generare espressioni di filtro.

Per elencare le risorse con un'etichetta department:shipping, utilizza la seguente specifica di filtro:

labels.department:shipping

Per elencare le risorse utilizzando più etichette, separa le coppie key:value con uno spazio. Lo spazio viene trattato come un operatore logico AND. Ad esempio, per elencare i set di dati con l'etichetta department:shipping e l'etichetta location:usa, utilizza la seguente specifica di filtro:

labels.department:shipping labels.location:usa

Puoi filtrare in base alla presenza di una sola chiave, anziché in base a una coppia chiave-valore. La seguente specifica di filtro elenca tutti i set di dati con l'etichetta department, indipendentemente dal valore.

labels.department

Una specifica di filtro equivalente utilizza un asterisco per rappresentare tutti i valori possibili associati alla chiave department.

labels.department:*

Puoi anche utilizzare i tag in una specifica di filtro. Ad esempio, per elencare le risorse con l'etichetta department:shipping e il tag test_data, utilizza la seguente specifica di filtro:

labels.department:shipping labels.test_data

Filtrare i set di dati nello strumento a riga di comando bq e nell'API

Per filtrare i set di dati utilizzando l'API, lo strumento a riga di comando bq o le librerie client:

bq

Esegui il comando bq ls con il flag --filter. Se stai elencando i set di dati in un progetto diverso da quello predefinito, specifica il flag --project_id.

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

Sostituisci quanto segue:

  • filter_specification è una specifica di filtro valida.
  • project_id è l'ID progetto.

Esempi:

Inserisci il seguente comando per elencare i set di dati nel progetto predefinito con un'etichetta department:shipping:

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

Inserisci il seguente comando per elencare i set di dati nel progetto predefinito con un'etichetta department:shipping e un tag test_data.

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

Inserisci il seguente comando per elencare i set di dati in myotherproject con un'etichetta department:shipping:

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

L'output di ciascuno di questi comandi restituisce un elenco di set di dati simile al seguente. 

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

API

Chiama il datasets.list metodo dell'API e fornisci la specifica di filtro utilizzando la proprietà filter.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Go API BigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java BigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Node.js API BigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API PythonBigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 


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

Passaggi successivi