更新標籤

本頁面說明如何為 BigQuery 資源更新標籤。

更新資料集標籤

資料集標籤的更新方式如下:

  • 使用 Cloud Console 或 BigQuery 傳統網頁版 UI
  • 使用指令列工具的 bq update 指令
  • 呼叫 datasets.patch API 方法
  • 使用用戶端程式庫

所需權限

您至少要具備 bigquery.datasets.update 權限,才能更新資料集標籤。以下是具有 bigquery.datasets.update 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataOwner
  • bigquery.admin

此外,當具備 bigquery.datasets.create 權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者更新資料集的標籤。

如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱預先定義的角色與權限一文。

更新資料集標籤

在資料集中更新標籤的方式如下:

主控台

  1. 在 Cloud Console 中,選取資料集。

  2. 在「Dataset Details」(資料集詳細資料) 頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。

    標籤鉛筆圖示

  3. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
    • 修改現有的鍵或值以更新標籤。
    • 按一下 [Update] (更新),儲存您所做的變更。

傳統版 UI

  1. 在網頁版 UI 中,選取資料集。

  2. 在「Dataset Details」(資料集詳細資料) 頁面中,按一下「Labels」(標籤) 右側的 [Edit] (編輯)。

    編輯標籤

  3. 在「Edit Labels」(編輯標籤) 對話方塊中:

    • 如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
    • 修改現有的鍵或值以更新標籤。
    • 按一下 [OK] (確定)。

      新增標籤

CLI

如要加入其他標籤或更新資料集標籤,請發出 bq update 指令並搭配使用 set_label 旗標。重複使用這個旗標即可加入或更新多個標籤。

如果資料集位於預設專案以外的專案中,請使用下列格式將專案 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,請輸入下列指令。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));
}

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
# 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

更新資料表和視圖標籤

資料表或檢視表建立後,您可以使用以下方式更新標籤:

  • 使用 Cloud Console 或 BigQuery 傳統網頁版 UI
  • 使用指令列工具的 bq update 指令
  • 呼叫 tables.patch API 方法
    • 由於系統會將檢視表當做資料表資源處理,因此可以使用 tables.patch 方法來修改檢視表和資料表。
  • 使用用戶端程式庫

所需權限

您至少要具備 bigquery.tables.update 權限,才能更新資料表或檢視表標籤。以下是具有 bigquery.tables.update 權限的預先定義 Cloud IAM 角色:

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

此外,當具備 bigquery.datasets.create 權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者更新資料集標籤,以及資料集內資料表和檢視表的標籤。

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限,請參閱預先定義的角色和權限

更新資料表或檢視表標籤

如何更新資料表或檢視表標籤:

主控台

  1. 在 Cloud Console 中選取資料表或檢視表。

  2. 按一下 [Details] (詳細資料) 分頁標籤,然後按一下「Labels」(標籤) 右側的鉛筆圖示。

  3. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個鍵只能在每個資料表或檢視表使用一次,但在不同資料集的資料表或檢視表中可使用同一個鍵。
    • 修改現有的鍵或值以更新標籤。
    • 按一下 [Update] (更新),儲存您所做的變更。

傳統版 UI

  1. 在網頁版 UI 中,選取資料表或視圖。

  2. 在詳細資料頁面中,按一下「Labels」(標籤) 右側的 [Edit] (編輯)。這個範例會顯示資料表的詳細資料。

    編輯標籤

  3. 在「Edit Labels」(編輯標籤) 對話方塊中:

    • 如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個鍵只能在每個資料表或檢視表使用一次,但在不同資料集的資料表或檢視表中可使用同一個鍵。
    • 修改現有的鍵或值以更新標籤。
    • 按一下 [OK] (確定)。

      新增標籤

CLI

如要加入其他標籤或更新資料表/檢視表標籤,請發出 bq update 指令並搭配使用 set_label 旗標。重複使用這個旗標即可加入或更新多個標籤。

如果資料表或檢視表位於預設專案以外的專案中,請使用下列格式將專案 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 做為標籤鍵。例如,如要在 mytable 中,將 department: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));
}

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()
# 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 權限

以下是具有 bigquery.datasets.update 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataOwner
  • bigquery.admin

以下是具有 bigquery.tables.update 權限的預先定義 Cloud IAM 角色:

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

此外,當具備 bigquery.datasets.create 權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者更新資料集標籤,以及資料集內資料表和檢視表的標籤。

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限,請參閱預先定義的角色和權限

將標籤轉換為標記

如何將標籤轉換為標記:

主控台

  1. 在 Cloud Console 中選取資料集、資料表或檢視表。

  2. 如果是資料集,資料集詳細資料頁面會自動開啟。如果是資料表和檢視表,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。

    資料表詳細資料

  3. 在詳細資料頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。

    標籤鉛筆圖示

  4. 在「Edit labels」(編輯標籤) 對話方塊中:

    • 刪除現有標籤的值。
    • 按一下 [Update] (更新)

傳統版 UI

  1. 在網頁版 UI 中,選取資料集、資料表或檢視表。

  2. 如果是資料集,「Dataset Details」(資料集詳細資料) 頁面會自動開啟。如果是資料表和檢視表,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。

  3. 在詳細資料頁面的「Labels」(標籤) 右側,按一下 [Edit] (編輯)。

  4. 在「Edit Labels」(編輯標籤) 對話方塊中:

    • 刪除現有標籤的值。
    • 按一下 [OK] (確定)。

      新增標記

CLI

如要將標籤轉換為標記,請將 bq update 指令搭配 set_label 旗標使用。請指定鍵並在後面加入冒號,但不要指定值。這樣就可以將現有的標籤更新為標記。

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

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
需要協助嗎?請前往我們的支援網頁