使用标签过滤资源

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

• 使用 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 控制台：

1. 在 Google Cloud 控制台中，找到探索器窗格。

2. 在搜索栏中，输入 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 文档中的使用标签。