更新标签

本页介绍如何更新 BigQuery 资源上的标签。

准备工作

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

更新数据集标签

数据集标签可通过以下方式更新：

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

所需权限

如需更新数据集标签，您需要拥有 bigquery.datasets.update IAM 权限。

以下每个预定义 IAM 角色都包含更新数据集标签所需的权限：

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外，如果您拥有 bigquery.datasets.create 权限，则可以更新自己创建的数据集的标签。

如需详细了解 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 与要添加或更新的标签的键值对相对应。如果您指定与现有标签相同的键，则系统会更新现有标签的值。键必须是唯一的。
  • project_id 是项目 ID。
  • dataset 是要更新的数据集。

示例：

要更新 mydataset 的 department 标签，请输入 bq update 命令并将 department 指定为标签键。例如，要将 department:shipping 标签更新为 department:logistics，请输入以下命令。mydataset 属于 myotherproject，而非默认项目。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

输出如下所示。

Dataset 'myotherproject:mydataset' successfully updated.

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 runLabelDataset() {
    // 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))

更新表和视图标签

创建表或视图后，可通过以下方式更新标签：

  • 使用 Google Cloud 控制台
  • 使用 bq 命令行工具的 bq update 命令
  • 调用 tables.patch API 方法
    • 由于视图被视为表资源，因此您可以使用 tables.patch 方法来修改视图和表。
  • 使用客户端库

所需权限

如需更新表或视图标签，您需要拥有 bigquery.tables.update IAM 权限。

以下预定义 IAM 角色都包含更新表或视图标签所需的权限：

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外，如果您拥有 bigquery.datasets.create 权限，则可以更新自己创建的数据集中的表和视图标签。

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

更新表或视图标签

如需更新表或视图标签，请执行以下操作：

控制台

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

  2. 点击详细信息标签页，然后点击标签右侧的铅笔图标。

  3. 在修改标签对话框中：

    • 要应用更多标签，请点击添加标签。每个键只能在每个表或视图内使用一次，但您可以在不同数据集内的表或视图中使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击更新以保存更改。

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 与要添加或更新的标签的键值对相对应。如果您指定与现有标签相同的键，则系统会更新现有标签的值。键必须是唯一的。
  • project_id 是项目 ID。
  • dataset 是包含您要更新的表或视图的数据集。
  • table_or_view 是要更新的表或视图的名称。

示例：

要更新 mytable 的 department 标签，请输入 bq update 命令并将 department 指定为标签键。例如，要将 department:shipping 标签更新为 mytable 的 department:logistics，请输入以下命令。mytable 属于 myotherproject，而非默认项目。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

输出如下所示：

Table 'myotherproject:mydataset.mytable' successfully updated.

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 runLabelTable() {
    // 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()
# 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

更新作业标签

目前不支持更新作业标签。要更新作业标签，请使用指定的新标签重新提交作业。

将标签转换为标记

如果一个标签的键为空值，则此标签用作标记。您可以创建一个未设定值的新标签，也可以将现有标签转换为数据集、表或视图上的标记。作业标签无法转换为标记。

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

所需权限

如需将标签转换为标记，您需要拥有以下 IAM 权限：

  • bigquery.datasets.update（可让您转换数据集标签）
  • bigquery.tables.update（可让您转换表或视图标签）

以下预定义 IAM 角色都包含转换数据集标签所需的权限：

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

以下预定义 IAM 角色都包含转换表或视图标签所需的权限：

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外，如果您拥有 bigquery.datasets.create 权限，则可以更新自己创建的数据集的标签以及这些数据集中的表和视图。

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

将标签转换为标记

如需将标签转换为标记，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台中，选择数据集、表或视图。

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

    表详细信息

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

    标签铅笔

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

    • 删除现有标签的值。
    • 点击更新。

bq

要将标签转换为标记，请使用带 set_label 标志的 bq update 命令。指定键，再后接英文冒号，但不指定值。这会将现有标签更新为标记。

bq update \
--set_label key: \
resource_id

其中：

  • key: 是要更新为标记的标签键。
  • resource_id 是有效的数据集、表或视图名称。如果资源属于非默认项目，请按以下格式添加项目 ID：project_id:dataset。

示例：

输入以下命令可将 mydataset 的现有 test_data:development 标签更新为标记。mydataset 属于 myotherproject，而非默认项目。

bq update --set_label test_data: myotherproject:mydataset

输出如下所示：

Dataset 'myotherproject:mydataset' successfully updated.

API

如需将现有标签转换为标记，请调用 datasets.patch 方法或 tables.patch 方法，并将数据集资源或表资源中的标签值替换为空字符串 ("")。

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

后续步骤