使用标签过滤资源

如需使用标签过滤资源，您可以执行以下操作之一：

使用 Google Cloud 控制台中的搜索栏。
创建用于 API、bq 命令行工具或客户端库的过滤规范。

限制

API、bp 命令行工具和客户端库仅支持对数据集进行过滤。
您无法在任何 BigQuery 工具中按标签过滤作业。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。

所需权限

如需使用标签过滤资源，您必须能够检索资源元数据。如需使用标签来过滤资源，您需要拥有以下 IAM 权限：

bigquery.datasets.get（可让您过滤数据集）
bigquery.tables.get（可让您过滤表和视图）

以下预定义 IAM 角色都包含过滤数据集所需的权限：

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

以下预定义 IAM 角色都包含过滤表和视图所需的权限：

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

此外，如果您拥有 bigquery.datasets.create 权限，则可以过滤自己创建的资源。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

在 Google Cloud 控制台中过滤资源

如需生成已过滤的资源列表，请使用 Google Cloud 控制台：

在 Google Cloud 控制台中，找到探索器窗格。
在搜索栏中，输入 key 或 key:value 对。结果会包括所有部分匹配项。

例如，如需仅显示具有标签 department:shipping 的数据集，您可以输入 department 或 department:shipping。

在 API 或 bq 命令行工具中过滤数据集

目前，API、bp 命令行工具和客户端库仅支持对数据集进行过滤。

如需使用 API、bp 工具或客户端库过滤数据集，请创建过滤规范并使用该规范：

作为 bp 工具中 --filter 标志的参数
作为 API 的 datasets.list 方法中 filter 属性的值

过滤规范的限制

过滤规范具有以下限制：

仅支持 AND 逻辑运算符。系统会将用空格分隔的比较视为具有隐式 AND 运算符。
目前，唯一符合过滤条件的字段是 labels.key，其中 key 是标签的名称。
过滤最多可包含 10 个表达式。
过滤操作区分大小写。
目前，API、bp 命令行工具和客户端库仅支持对数据集进行过滤。

过滤规范示例

过滤规范使用以下语法：

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

替换以下内容：

field 以 labels.key 表示，其中 key 是标签键。
value 是可选的标签值。

以下示例展示了如何生成过滤表达式。

如需列出具有 department:shipping 标签的资源，请使用以下过滤规范：

labels.department:shipping

如需列出具有多个标签的资源，请使用空格分隔 key:value 对。系统会将空格视为逻辑 AND 运算符。例如，如需列出具有 department:shipping 标签和 location:usa 标签的数据集，请使用以下过滤规范：

labels.department:shipping labels.location:usa

您可以单独对键进行过滤，而不是匹配键值对。以下过滤规范可列出所有具有 department 标签的数据集，无论其值如何。

labels.department

下面的等效过滤规范使用星号表示与 department 键关联的所有可能值。

labels.department:*

您还可以在过滤规范中使用标记。例如，如需列出具有 department:shipping 标签和 test_data 标记的资源，请使用以下过滤规范：

labels.department:shipping labels.test_data

在 bq 命令行工具和 API 中过滤数据集

如需使用 API、bp 命令行工具或客户端库过滤数据集，请执行以下操作：

bq

发出带 --filter 标志的 bq ls 命令。如果您要列出非默认项目中的数据集，请指定 --project_id 标志。

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

替换以下内容：

filter_specification 是有效的过滤规范。
project_id 是您的项目 ID。

示例：

输入以下命令可列出默认项目中具有 department:shipping 标签的数据集：

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

输入以下命令可列出默认项目中具有 department:shipping 标签和 test_data 标记的数据集。

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

输入以下命令可列出 myotherproject 中具有 department:shipping 标签的数据集：

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

每个命令的输出都会返回一个数据集列表，如下所示。

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

API

调用 datasets.list API 方法，并使用 filter 属性提供过滤规范。

Go

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


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

后续步骤

了解如何为 BigQuery 资源添加标签。
了解如何针对 BigQuery 资源查看标签。
了解如何针对 BigQuery 资源更新标签。
了解如何针对 BigQuery 资源删除标签。
参阅 Resource Manager 文档中的使用标签。