更新標籤

本頁面說明如何為 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. 按一下「Details」(詳細資料) 分頁標籤，然後點選 「Edit details」(編輯詳細資料)。

  3. 在「Labels」(標籤) 區段中，修改現有的「Key」(鍵) 或「Value」(值) 欄位，即可更新標籤。如要套用其他標籤，請按一下「Add labels」(新增標籤)。每個鍵在每個資料集中只能使用一次，但您可以在相同專案的不同資料集裡使用同一個鍵。

  4. 按一下「儲存」。

SQL

使用 ALTER SCHEMA SET OPTIONS DDL 陳述式，為現有資料集設定標籤。設定標籤會覆寫資料集現有的標籤。以下範例會在資料集 mydataset 上設定單一標籤：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在查詢編輯器中輸入下列陳述式：

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

  3. 按一下「 執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

bq

如要加入其他標籤或更新資料集標籤，請發出 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，請輸入下列指令。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. 在「Labels」(標籤) 區段中，修改現有的「Key」(鍵) 或「Value」(值) 欄位，即可更新標籤。如要套用其他標籤，請按一下「Add labels」(新增標籤)。每個鍵在每個資料表或檢視表中只能使用一次，但您可以在不同資料集的資料表或檢視表中使用同一個鍵。

  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

如要加入其他標籤或更新資料表/檢視表標籤，請發出 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，請輸入下列指令。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

更新工作標籤

不支援更新工作標籤。如要更新工作標籤，請指定新的標籤並重新提交工作。

更新預留項目標籤

您可以更新預留項目的標籤。使用 SQL 更新標籤時，會覆寫預留項目現有的任何標籤。

必要的 IAM 角色

如要取得更新預留項目標籤所需的權限，請要求管理員授予您管理專案的 BigQuery 資源編輯者 (roles/bigquery.resourceEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 bigquery.reservations.update 權限，可更新預留項目的標籤。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

更新預留項目的標籤

如要更新預留項目的標籤，請按照下列步驟操作：

控制台

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在導覽選單中，按一下「Workload management」(工作負載管理)。

  3. 點選「Slot reservations」(運算單元預留項目) 分頁標籤。

  4. 找出要更新的預訂。

  5. 展開 「Actions」(動作) 選項。

  6. 按一下 [編輯]。

  7. 如要展開「Advanced settings」(進階設定) 部分，請按一下 展開箭頭。

  8. 更新鍵/值組合的名稱。

  9. 按一下「儲存」。

bq

如要更新預留項目的標籤，請執行 bq update 指令，並加上 set_label 旗標和 --reservation 旗標。如要更新多個標籤，請重複使用這個旗標。

bq update --set_label KEY:VALUE  --reservation RESERVATION_NAME

更改下列內容：

  • KEY:VALUE：要更新的預留項目標籤鍵/值組合。鍵不得重複。鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼，且可使用國際字元。如要更新預留項目的多個標籤，請重複使用 --set_label 旗標，並為每個標籤指定專屬鍵。
  • RESERVATION_NAME：預留項目名稱。

SQL

如要更新預留項目的標籤，請使用 ALTER RESERVATION SET OPTIONS DDL 陳述式，設定現有預留項目的標籤。設定標籤會覆寫預留項目現有的標籤。以下範例會為預留項目 myreservation 設定標籤：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在查詢編輯器中輸入下列陳述式：

    ALTER RESERVATION myreservation
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

  3. 按一下「 執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

將標籤轉換為標記

包含具有空白值的鍵的標籤可做為標記。您可以建立不含任何值的新標籤，或是將資料集內的現有標籤轉換成標記。您無法將工作標籤轉換為標記。

標記適用於標示資源，但不需要 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. 開啟「編輯詳細資料」窗格：

    • 如果是資料集，請按一下「Details」(詳細資料) 分頁標籤，然後按一下 「Edit details」(編輯詳細資料)。
    • 如為資料表或檢視表，請在詳細資料窗格中，依序點選 「Edit」>「Edit details」。

  3. 在「Labels」(標籤) 區段中，刪除要更新的標籤「Value」(值) 欄位中的值。

  4. 按一下「儲存」。

bq

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

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

後續步驟