將標籤新增至資源

本頁面說明如何為 BigQuery 資源加上標籤。

加入資料集標籤

建立 BigQuery 資料集時,可以使用指令列工具的 bq mk 指令或呼叫 datasets.insert API 方法加入標籤。如果資料集是透過 GCP Console 或傳統 BigQuery 網頁版 UI 建立的,則目前您無法在這類資料集中加入標籤。

本頁面說明如何在建立資料集後加入標籤。如要深入瞭解如何在建立資料集時加入標籤,請參閱建立資料集

將資料集建立好之後,您可透過下列方式來加入標籤:

  • 使用 GCP 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 中的 Cloud IAM 角色和權限,請參閱預先定義的角色和權限

在資料集中加入標籤

如何在建立資料集後加入標籤:

主控台

  1. 在 GCP Console 中選取資料集。

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

    標籤鉛筆圖示

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

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

傳統版 UI

  1. 在 BigQuery 網頁版 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」是您要加入標籤的資料集。

範例:

如要加入標籤以追蹤部門,請輸入 bq update 指令並指定 department 做為標籤鍵。例如,如要將 department:shipping 標籤加入預設專案中的 mydataset,請輸入:

    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 參考說明文件

// 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 快速入門導覽課程:使用用戶端程式庫中的操作說明設定 Go。詳情請參閱 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

加入資料表和檢視表標籤

建立資料表或檢視表後,您可以透過下列方式加上標籤:

  • 使用指令列工具的 bq mk 指令
  • 呼叫 tables.insert API 方法

本頁面說明如何在現有資料表或檢視表中加入標籤。如要深入瞭解如何在建立資料表或檢視表時加入標籤,請參閱建立資料表建立檢視表

建立資料表或檢視表後,您可以透過下列方式加入標籤:

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

由於系統會將檢視表當做資料表資源處理,因此可以使用 tables.patch 方法來修改檢視表和資料表。

所需權限

您至少要具備 bigquery.tables.updatebigquery.tables.get 權限,才能在現有資料表或檢視表中加入標籤。以下是具有 bigquery.tables.updatebigquery.tables.get 權限的預先定義 Cloud IAM 角色:

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

此外,具備 bigquery.datasets.create 權限的使用者在建立資料集時,會獲得 bigquery.dataOwner 存取權。 bigquery.dataOwner 存取權可讓使用者將標籤加到資料集中的資料表和檢視表。

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

在資料表或檢視表中加入標籤

如何在現有資料表或檢視表中加入標籤:

主控台

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

  2. 按一下 [Details] (詳細資料) 分頁標籤。

    資料表詳細資料

  3. 按一下「Labels」(標籤) 右側的鉛筆圖示

    標籤鉛筆圖示

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

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

DDL

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表及檢視表。

詳情請參閱使用資料定義語言陳述式一文。

如要在 GCP Console 中使用 DDL 陳述式加入標籤:

  1. 按一下 [Compose new query] (撰寫新查詢)

  2. 將您的 DDL 陳述式輸入到「Query editor」(查詢編輯器) 的文字區域。

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

  3. 按一下 [Run query] (執行查詢)

傳統版 UI

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

  2. 在「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.table_or_view

其中:

  • 「key:value」是您要加入的標籤的鍵/值組合,鍵不得重複。
  • 「project_id」是您的專案 ID。
  • 「dataset」是您要加入標籤的資料表或檢視表所屬的資料集。
  • 「table_or_view」是您要加入標籤的資料表或檢視表名稱。

範例:

如要加入可追蹤部門的資料表標籤,請輸入 bq update 指令並指定 department 做為標籤鍵。例如,如要將 department:shipping 標籤加入預設專案中的 mytable,請輸入:

    bq update --set_label department:shipping mydataset.mytable

如要加入可追蹤部門的檢視表標籤,請輸入 bq update 指令並指定 department 做為標籤鍵。例如,如要將 department:shipping 標籤加入預設專案中的 myview,請輸入:

    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 參考說明文件

// 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 快速入門導覽課程:使用用戶端程式庫中的操作說明設定 Go。詳情請參閱 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

加入工作標籤

您可以使用指令列工具的 --label 標記透過指令列在查詢工作中加入標籤。指令列工具僅支援在查詢工作中加入標籤。

如果某個工作是透過 API 提交,您也可以在其中加入標籤,方法是當您呼叫 jobs.insert 時,在工作設定中指定 labels 屬性。API 可用於在任何工作類型中加入標籤。

您無法在待處理、執行中或已完成的工作中加入或更新標籤。

在工作中加入標籤後,標籤就會納入您的帳單資料中。

所需權限

您不需要具備特殊權限就能在工作中加入標籤。如果您具有 bigquery.jobs.create 權限,則可在提交工作時加入標籤。

您至少要有 bigquery.jobs.create 權限才能執行工作。 由 BigQuery 自動建立的工作和您透過程式執行的工作,都需要 bigquery.jobs.create 權限。

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

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

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

在工作中加入標籤

如何在工作中加入標籤:

主控台

GCP Console 不支援在工作中加入標籤。

傳統版 UI

傳統 BigQuery 網頁版 UI 不支援在工作中加入標籤。

CLI

如要在查詢工作中加入標籤,請發出 bq query 指令並搭配使用 --label 標記。重複使用該標記即可加入多個標籤。--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 在任何類型的工作中加入標籤。

新增標記

包含具有空白值的鍵的標籤可做為標記。您可以建立沒有值的新標籤,也可以將現有的標籤轉換為標記。

標記在要為資源加上標籤的情況下非常有用,但您不需要使用 key:value 格式。例如,如果您的資料表包含由多個群組 (支援和開發等) 使用的測試資料,您可以在該資料表中加入 test_data 標記以供識別。

如何新增標記:

主控台

  1. 在 GCP Console 中,選取適當的資源 (資料集、資料表或檢視表)。

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

    資料表詳細資料

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

    標籤鉛筆圖示

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

    • 按一下 [Add label] (新增標籤)
    • 輸入新的鍵並將值留空。如要套用其他標記,請按一下 [Add label] (新增標籤),並重複執行相同步驟。
    • 按一下 [Update] (更新),儲存您所做的變更。

DDL

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表及檢視表。

詳情請參閱使用資料定義語言陳述式一文。

如要在 GCP Console 中使用 DDL 陳述式加入標記:

  1. 按一下 [Compose new query] (撰寫新查詢)

  2. 將您的 DDL 陳述式輸入到「Query editor」(查詢編輯器) 的文字區域。

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

  3. 按一下 [Run query] (執行查詢)

傳統版 UI

  1. 在網頁版 UI 中,選取適當的資源 (資料集、資料表或檢視表)。

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

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

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

    • 輸入新的鍵並將值留空。如要套用其他標記,請按一下 [Add Label] (新增標籤)
    • 按一下 [OK] (確定)

      新增標記

CLI

如要在現有資源中加入標記,請將 bq update 指令搭配 set_label 標記使用。請指定鍵並在後面加入冒號,但不要指定值。

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

後續步驟

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

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

這個網頁