为资源添加标签

本页面介绍了如何为 BigQuery 资源添加标签。

添加数据集标签

在创建 BigQuery 数据集时，您可以使用 bq 命令行工具的 bq mk 命令或调用 datasets.insert API 方法来为该数据集添加标签。目前，您不能向通过 Cloud Console 创建的数据集添加标签。

本页面介绍如何在创建数据集后向其添加标签。如需详细了解如何在创建数据集时添加标签，请参阅创建数据集。

在创建数据集后添加标签的方法如下：

使用 Cloud Console
使用 bq 命令行工具的 bq update 命令
调用 datasets.patch API 方法
使用客户端库

向数据集添加标签时，标签不会传播到该数据集中的资源。表或视图不会继承数据集标签。向数据集添加标签后，标签会包含在存储空间结算数据中，但您不会在与作业相关的结算数据中看到数据集标签。

所需权限

如需为现有数据集添加标签，您必须至少具有 bigquery.datasets.update 权限。以下预定义的 IAM 角色包含 bigquery.datasets.update 权限：

bigquery.dataOwner
bigquery.admin

此外，如果用户具有 bigquery.datasets.create 权限，则当该用户创建数据集时，系统会为其授予该数据集的 bigquery.dataOwner 访问权限。具备 bigquery.dataOwner 访问权限的用户可为其数据集添加标签。

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

为数据集添加标签

如需在创建数据集后为其添加标签，请执行以下操作：

控制台

在 Cloud Console 中，选择相应的数据集。
在数据集详细信息页面上，点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作：
- 点击添加标签。
- 输入键和值以添加标签。如需应用更多标签，请点击添加标签。每个键只能在每个数据集内使用一次，但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。

bq

如需为现有数据集添加标签，请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加多个标签。

如果数据集属于非默认项目，请按以下格式将相应项目 ID 添加到数据集：PROJECT_ID:DATASET。

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

替换以下内容：

KEY:VALUE：您要添加的标签的键值对。键必须是唯一的。
PROJECT_ID：您的项目 ID。
DATASET：您要为其添加标签的数据集。

示例：

如需添加标签来跟踪部门，请输入 bq update 命令并将 department 指定为标签键。例如，如要为默认项目中的 mydataset 添加 department:shipping 标签，请输入以下命令：

    bq update --set_label department:shipping mydataset

如需为数据集添加多个标签，请重复使用 set_label 标志并为每个标签指定唯一键。例如，如要为默认项目中的 mydataset 添加 department:shipping 标签和 cost_center:logistics 标签，请输入以下命令：

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

如需为现有数据集添加标签，请调用 datasets.patch 方法，并填充数据集资源的 labels 属性。

由于 datasets.update 方法会替换整个数据集资源，因此最好使用 datasets.patch 方法。

Go

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

在 GitHub 上查看反馈

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。

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

在 GitHub 上查看反馈

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Node.js

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

在 GitHub 上查看反馈

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

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

在 GitHub 上查看反馈


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

添加表和视图标签

在创建表或视图时向其添加标签的方法如下：

使用 bq 命令行工具的 bq mk 命令
调用 tables.insert API 方法

本页面介绍如何向现有表或视图添加标签。如需详细了解如何在创建表或视图时添加标签，请参阅创建表或创建视图。

在创建表或视图后向其添加标签的方法如下：

使用 Cloud Console
使用 bq 命令行工具的 bq update 命令
调用 tables.patch API 方法
使用客户端库

由于视图被视为表资源，因此您可以使用 tables.patch 方法来修改视图和表。

所需权限

如需为现有表或视图添加标签，您必须至少具有 bigquery.tables.update 和 bigquery.tables.get 权限。以下预定义 IAM 角色具有 bigquery.tables.update 和 bigquery.tables.get 权限：

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

此外，如果用户具有 bigquery.datasets.create 权限，则当该用户创建数据集时，系统会为其授予该数据集的 bigquery.dataOwner 访问权限。具备 bigquery.dataOwner 访问权限的用户可以为其数据集中的表和视图添加标签。

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

为表或视图添加标签

如需为现有表或视图添加标签，请执行以下操作：

控制台

在 Cloud Console 中选择表或视图。
点击详细信息标签页。
点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作：
- 点击添加标签。
- 输入键和值以添加标签。如需应用更多标签，请点击添加标签。每个键只能在每个数据集内使用一次，但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。

SQL

借助数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表和视图。

详细了解如何使用数据定义语言语句。

如需在 Cloud Console 中使用 DDL 语句添加标签，请执行以下操作：

点击编写新查询。

在查询编辑器文本区域中，输入您的 DDL 语句。

 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   labels=[("department", "shipping"), ("cost_center", "logistics")]
 )

点击运行查询。

bq

如需为现有表或视图添加标签，请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加多个标签。

如果表或视图属于非默认项目，请按以下格式将相应项目 ID 添加到数据集：project_id:dataset。

bq update \
--set_label KEY:VALUE \
PROJECT_ID:DATASET.TABLE_OR_VIEW

替换以下内容：

KEY:VALUE：您要添加的标签的键值对。键必须是唯一的。
PROJECT_ID：您的项目 ID。
DATASET：包含您要为其添加标签的表或视图的数据集。
TABLE_OR_VIEW：您要为其添加标签的表或视图的名称。

示例：

如需添加表标签来跟踪部门，请输入 bq update 命令并将 department 指定为标签键。例如，如要为默认项目中的 mytable 添加 department:shipping 标签，请输入以下命令：

    bq update --set_label department:shipping mydataset.mytable

如需添加视图标签来跟踪部门，请输入 bq update 命令并将 department 指定为标签键。例如，如要为默认项目中的 myview 添加 department:shipping 标签，请输入以下命令：

    bq update --set_label department:shipping mydataset.myview

如需为表或视图添加多个标签，请重复使用 set_label 标志并为每个标签指定唯一键。例如，如要为默认项目中的 mytable 添加 department:shipping 标签和 cost_center:logistics 标签，请输入以下命令：

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

如需为现有表或视图添加标签，请调用 tables.patch 方法，并填充表资源的 labels 属性。

由于视图被视为表资源，因此您可以使用 tables.patch 方法来修改视图和表。

由于 tables.update 方法会替换整个数据集资源，因此最好使用 tables.patch 方法。

Go

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

在 GitHub 上查看反馈

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。

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

在 GitHub 上查看反馈

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Node.js

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

在 GitHub 上查看反馈

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

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

在 GitHub 上查看反馈

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

为作业添加标签

您可以通过命令行使用 bq 命令行工具的 --label 标志，为查询作业添加标签。bq 工具仅支持向查询作业添加标签。

您也可以在通过 API 提交作业时为该作业添加标签，具体做法是调用 jobs.insert 方法并在作业配置中指定 labels 属性。API 支持为任何类型的作业添加标签。

您不能为待处理、正在运行或已完成的作业添加标签或更新标签。

向作业添加标签后，标签会包含在您的结算数据中。

所需权限

为作业添加标签不需要特殊权限。如果您具有 bigquery.jobs.create 权限，则可在提交作业时为其添加标签。

如要运行作业，您必须至少具有 bigquery.jobs.create 权限。 BigQuery 自动创建的作业和您通过编程方式运行的作业都需要 bigquery.jobs.create 权限。

以下预定义的 IAM 角色包含 bigquery.jobs.create 权限：

bigquery.user
bigquery.jobUser
bigquery.admin

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

为作业添加标签

如需为作业添加标签，请执行以下操作：

控制台

Cloud Console 不支持为作业添加标签。

bq

如需为查询作业添加标签，请发出带 --label 标志的 bq query 命令。重复使用该标志可添加多个标签。--nouse_legacy_sql 标志表示您的查询采用标准 SQL 语法。

bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'

替换以下内容：

KEY:VALUE：您要添加到查询作业的标签的键值对。键不得重复。如需为查询作业添加多个标签，请重复使用 --label 标志并为每个标签指定唯一键。
QUERY：有效的标准 SQL 查询。

示例：

如需为查询作业添加标签，请输入以下命令：

    bq query \
    --label department:shipping \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

如需为查询作业添加多个标签，请重复使用 --label 标志并为每个标签指定唯一键。例如，如要为查询作业添加 department:shipping 标签和 cost_center:logistics 标签，请输入以下命令：

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

如需为作业添加标签，请调用 jobs.insert 方法并填充作业配置的 labels 属性。您可以使用 API 为任何类型的作业添加标签。

添加标记

如果一个标签的键没有相应的值，则此标签用作标记。您可以创建一个未设定值的新标签，也可以将现有标签转变为标记。

如果您需要为资源添加标签，但不需要采用键值格式，则可以采用标记。例如，如果您的表包含由多个群组（支持、开发等）使用的测试数据，您可以为该表添加 test_data 标记，以作识别之用。

如需添加标记，请执行以下操作：

控制台

在 Cloud Console 中，选择相应的资源（数据集、表或视图）。
对于数据集，系统会自动打开“数据集详情”页面。对于表和视图，点击详细信息以打开详情页面。
在详情页面上，点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作：
- 点击添加标签。
- 输入新键并将值留空。如需应用更多标记，请点击添加标签并重复。
- 点击更新以保存更改。

SQL

借助数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表及视图。

详细了解如何使用数据定义语言语句。

如需在 Cloud Console 中使用 DDL 语句添加标记，请执行以下操作：

点击编写新查询。

在查询编辑器文本区域中，输入您的 DDL 语句。

 ALTER TABLE mydataset.mytable
 SET OPTIONS (
   labels=[("tag1", ""), ("tag2", "")]
 )

点击运行查询。

bq

如需为现有资源添加标记，请使用带 set_label 标志的 bq update 命令。请指定键并在后面加上英文冒号，但不指定值。

bq update --set_label KEY: RESOURCE_ID

替换以下内容：

KEY:：要用作标记的标签键。
RESOURCE_ID：有效的数据集、表或视图名称。如果资源不属于默认项目，请按以下格式添加相应项目 ID：PROJECT_ID:DATASET。

示例：

要为 mydataset.mytable 创建 test_data 标记，请输入以下命令。mydataset 属于默认项目。

bq update --set_label test_data: mydataset

API

调用 datasets.patch 方法或 tables.patch 方法，然后添加标签，并将数据集资源或表资源中的标签值设置为空字符串 ("")。您可以将现有标签转换为标记，方法是将标签值替换为空字符串。

由于视图被视为表资源，因此您可以使用 tables.patch 方法来修改视图和表。另外，由于 tables.update 方法会替换整个数据集资源，因此最好使用 tables.patch 方法。

后续步骤

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