为资源添加标签

本页面介绍了如何为 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 角色和权限,请参阅预定义的角色和权限

为数据集添加标签

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

控制台

  1. 在 Cloud Console 中,选择相应的数据集。

  2. 在数据集详细信息页面上,点击标签右侧的铅笔图标。

    标签铅笔。

  3. 修改标签对话框中执行以下操作:

    • 点击添加标签
    • 输入键和值以添加标签。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击更新以保存更改。

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 参考文档

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 参考文档

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 参考文档

// 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 参考文档


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.updatebigquery.tables.get 权限。以下预定义 IAM 角色具有 bigquery.tables.updatebigquery.tables.get 权限:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

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

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

为表或视图添加标签

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

控制台

  1. 在 Cloud Console 中选择表或视图。

  2. 点击详细信息标签页。

    表详细信息。

  3. 点击标签右侧的铅笔图标。

    标签铅笔。

  4. 修改标签对话框中执行以下操作:

    • 点击添加标签
    • 输入键和值以添加标签。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击更新以保存更改。

SQL

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

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

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

  1. 点击编写新查询

  2. 查询编辑器文本区域中,输入您的 DDL 语句。

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

  3. 点击运行查询

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 参考文档

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 参考文档

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 参考文档

// 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 参考文档

# 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 标记,以作识别之用。

如需添加标记,请执行以下操作:

控制台

  1. 在 Cloud Console 中,选择相应的资源(数据集、表或视图)。

  2. 对于数据集,系统会自动打开“数据集详情”页面。对于表和视图,点击详细信息以打开详情页面。

    表详细信息。

  3. 在详情页面上,点击标签右侧的铅笔图标。

    标签铅笔。

  4. 修改标签对话框中执行以下操作:

    • 点击添加标签
    • 输入新键并将值留空。如需应用更多标记,请点击添加标签并重复。
    • 点击更新以保存更改。

SQL

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

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

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

  1. 点击编写新查询

  2. 查询编辑器文本区域中,输入您的 DDL 语句。

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

  3. 点击运行查询

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 方法。

后续步骤