为资源添加标签

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

准备工作

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

为数据集添加标签

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

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

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

  • 使用 Google Cloud 控制台
  • 使用 SQL DDL 语句
  • 使用 bq 命令行工具的 bq update 命令
  • 调用 datasets.patch API 方法
  • 使用客户端库

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

如需详细了解标签的格式，请参阅标签要求。

所需 IAM 角色

如需获得为现有数据集添加标签所需的权限，请让您的管理员为您授予 BigQuery Data Editor (roles/bigquery.dataEditor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供 bigquery.datasets.update 权限，该权限是为现有数据集添加标签所必需的。

您也可以使用自定义角色或其他预定义角色来获取此权限。

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

为数据集添加标签

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

控制台

  1. 在 Google Cloud 控制台中，选择相应的数据集。

  2. 在数据集详情页面上，点击标签右侧的铅笔图标。

    标签铅笔。

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

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

SQL

使用 ALTER SCHEMA SET OPTIONS DDL 语句在现有数据集上设置标签。设置标签会覆盖数据集中的所有现有标签。以下示例在数据集 mydataset 上设置一个标签：

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中，输入以下语句：

    ALTER SCHEMA mydataset
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

  3. 点击 运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

bq

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

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

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

替换以下内容：

  • KEY:VALUE：您要添加的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。
  • 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 参考文档。

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

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    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();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \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 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 参考文档。

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


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

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

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

  • 使用 Google Cloud 控制台
  • 使用 bq 命令行工具的 bq update 命令
  • 调用 tables.patch API 方法
  • 使用客户端库

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

所需 IAM 角色

如需获得为现有表或视图添加标签所需的权限，请让您的管理员为您授予 BigQuery Data Editor (roles/bigquery.dataEditor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供为现有表或视图添加标签所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需为现有表或视图添加标签，您需要拥有以下权限：

  • bigquery.tables.update
  • bigquery.tables.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

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

为表或视图添加标签

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

控制台

  1. 在 Google Cloud 控制台中选择表或视图。

  2. 点击详情标签页。

    表详细信息。

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

    标签铅笔。

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

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

SQL

使用 ALTER TABLE SET OPTIONS DDL 语句在现有表上设置标签，或使用 ALTER VIEW SET OPTIONS DDL 语句 在现有视图上设置标签。设置标签会覆盖表或视图上的所有现有标签。以下示例在表 mytable 上设置两个标签：

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中，输入以下语句：

    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：您要添加的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。
  • 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 参考文档。

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

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    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();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \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 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 参考文档。

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

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API request

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

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

print(f"Added {table.labels} to {table_id}.")

为作业添加标签

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

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

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

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

所需 IAM 角色

如需获得为作业添加标签所需的权限，请让您的管理员为您授予 BigQuery User (roles/bigquery.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供 bigquery.jobs.create 权限，该权限是为作业添加标签所必需的。

您也可以使用自定义角色或其他预定义角色来获取此权限。

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

为作业添加标签

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

bq

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

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

请替换以下内容：

  • KEY:VALUE：您要添加到查询作业的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。如需为查询作业添加多个标签，请重复使用 --label 标志并为每个标签指定唯一键。
  • QUERY：有效的 GoogleSQL 查询。

示例：

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

    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 为任何类型的作业添加标签。

将会话中的作业与标签相关联

如果在会话中运行查询，则可以使用 BigQuery 多语句查询为会话中的所有未来查询作业分配标签。

SQL

通过运行以下查询，在会话中设置 @@query_label 系统变量：

  SET @@query_label = "KEY:VALUE";

  • KEY:VALUE：要分配给会话中所有未来查询的标签的键值对。 您还可以添加多个键值对，并用英文逗号分隔（例如 SET @@query_label = "key1:value1,key2:value2"）。键必须是唯一的。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。

示例：

  SET @@query_label = "cost_center:logistics";

API

如需在使用 API 调用运行查询时为会话中的查询作业添加标签，请调用 jobs.insert 方法，并填充 connectionProperties 作业配置的 query_label 属性。

将查询标签与会话相关联并在会话内运行查询后，您就可以收集具有该查询标签的查询的审核日志。如需了解详情，请参阅 BigQuery 的审核日志参考文档。

添加不带值的标签

如果一个标签有键，但值为空，则此标签有时称为标记。请勿将其与标记资源混淆。如需了解详情，请参阅标签和标记。您可以创建一个没有值的新标签，也可以从现有标签键中移除值。

如果您要为资源添加标签，但不需要采用键值格式，则没有值的标签会很有用。比方说，如果一个表包含由多个群组（如支持或开发）使用的测试数据，您可以为该表添加 test_data 标签，以作识别之用。

如需添加没有值的标签，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台中，选择相应的资源（数据集、表或视图）。

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

    表详细信息。

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

    标签铅笔。

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

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

SQL

如需添加没有值的标签，请使用 ALTER TABLE SET OPTIONS DDL 语句：

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中，输入以下语句：

    ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels=[("key1", ""), ("key2", "")]);

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

后续步骤