更新标签

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

更新数据集标签

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

  • 使用 GCP Console 或经典版 BigQuery 网页界面
  • 使用命令行工具的 bq update 命令
  • 调用 datasets.patch API 方法
  • 使用客户端库

所需权限

如需更新数据集标签,您至少必须获得 bigquery.datasets.update 权限。以下预定义的 Cloud IAM 角色包含 bigquery.datasets.update 权限:

  • bigquery.dataOwner
  • bigquery.admin

此外,如果用户具有 bigquery.datasets.create 权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner 访问权限。 借助 bigquery.dataOwner 访问权限,用户可以更新数据集上的标签。

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问权限控制

更新数据集标签

要更新数据集上的标签,请执行以下操作:

Console

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

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

    标签铅笔

  3. 修改标签对话框中:

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

传统版界面

  1. 在网页界面,选择相应的数据集。

  2. 数据集详情页面,点击标签右侧的修改

    修改标签

  3. Edit Labels 对话框中:

    • 要应用更多标签,请点击 Add Label。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击 OK

      新建标签

CLI

要添加其他标签或更新数据集标签,请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加或更新多个标签。

如果数据集在默认项目以外的项目中,请按以下格式为数据集添加相应的项目 ID:[PROJECT_ID]:[DATASET]

bq update \
--set_label key:value \
project_id:dataset

其中:

  • key:value 对应于要添加或更新的标签的键值对。如果您指定与现有标签相同的键,则系统会更新现有标签的值。键必须是唯一的。
  • project_id 为您的项目 ID
  • dataset 是要更新的数据集

例如:

要更新 mydatasetdepartment 标签,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签更新为 department:logistics,请输入以下命令。mydatasetmyotherproject 中,而不在默认项目中。

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

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));
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

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

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

更新表和视图标签

创建表或视图后,您可以通过以下方式更新标签:

  • 使用 GCP Console 或经典版 BigQuery 网页界面
  • 使用命令行工具的 bq update 命令
  • 调用 tables.patch API 方法
    • 由于视图被视为表资源,因此您可以使用 tables.patch 方法修改视图和表。
  • 使用客户端库

所需权限

如需更新表或视图标签,您至少必须获得 bigquery.tables.update 权限。以下预定义的 Cloud IAM 角色包含 bigquery.tables.update 权限:

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

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

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限,请参阅访问权限控制

更新表或视图标签

要更新表或视图标签,请执行以下操作:

Console

  1. 在 GCP Console 中,选择相应的表或视图。

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

  3. 修改标签对话框中:

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

传统版界面

  1. 在网页界面,选择表或视图。

  2. 在详情页面,点击 Labels 右侧的 Edit。以下示例展示了表的详细信息。

    修改标签

  3. Edit Labels 对话框中:

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

      新标签

CLI

要添加其他标签或更新表或视图标签,请发出带 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 是您要更新的表或视图的名称

例如:

要更新 mytabledepartment 标签,请输入 bq update 命令并将 department 指定为标签键。例如,要将 mytabledepartment:shipping 标签更新为 department:logistics,请输入以下命令。mytablemyotherproject 中,不在默认项目中。

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

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));
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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 标记添加到该表,以作识别之用。

所需权限

将标签转换为标记所需的权限应至少与更新标签所需的权限相同。

  • bigquery.datasets.update,用于转换数据集标签
  • bigquery.tables.update,用于转换表或视图标签

以下预定义的 Cloud IAM 角色包含 bigquery.datasets.update 权限:

  • bigquery.dataOwner
  • bigquery.admin

以下预定义的 Cloud IAM 角色包含 bigquery.tables.update 权限:

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

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

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限,请参阅访问权限控制

将标签转换为标记

要将标签转换为标记,请执行以下操作:

Console

  1. 在 GCP Console 中,选择相应的数据集、表或视图。

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

    表详细信息

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

    标签铅笔

  4. 修改标签对话框中:

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

经典版界面

  1. 在网页界面,选择相应的数据集、表或视图。

  2. 对于数据集,系统会自动打开 Dataset Details 页面。对于表和视图,点击 Details 以打开详情页面。

  3. 在详情页面,点击 Labels 右侧的 Edit

  4. Edit Labels 对话框中:

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

      添加标记

CLI

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

bq update \
--set_label key: \
resource_id

其中:

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

示例:

输入以下命令可将 mydataset 的现有 test_data:development 标签更新为标记。mydatasetmyotherproject 中,不在默认项目中。

bq update --set_label test_data: myotherproject:mydataset

输出如下所示:

Dataset 'myotherproject:mydataset' successfully updated.

API

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

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

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面