將標籤新增至資源
本頁面說明如何為 BigQuery 資源加上標籤。
事前準備
授予身分與存取權管理 (IAM) 角色,讓使用者取得執行本文件中各項工作的必要權限。執行工作所需的權限會列在工作「所需的 IAM 角色」部分。
為資料集新增標籤
使用 bq 指令列工具的 bq mk
指令或呼叫 datasets.insert
API 方法建立 BigQuery 資料集時,可以加入標籤。如果資料集是使用 Google Cloud 主控台建立的,則無法加入標籤。
本頁面說明如何在建立資料集後加入標籤。如要深入瞭解如何在建立資料集時加入標籤,請參閱建立資料集。
您在資料集中加入標籤時,該資料集內的資源並不會套用這個標籤。資料表或檢視表不會沿用資料集標籤。此外,在資料集中加入標籤後,標籤就會列入儲存空間帳單資料中,但不會列入工作相關的帳單資料。
如要進一步瞭解標籤格式,請參閱「標籤相關規定」。
必要的 IAM 角色
如要取得在現有資料集新增標籤所需的權限,請向管理員要求授予 BigQuery 資料編輯者 (roles/bigquery.dataEditor
) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色包含 bigquery.datasets.update
權限,這是為現有資料集新增標籤所需的權限。
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
在資料集中加入標籤
如何在建立資料集後加入標籤:
主控台
在 Google Cloud 控制台中選取資料集。
在「Dataset Details」(資料集詳細資料) 頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。
在「Edit labels」(編輯標籤) 對話方塊中:
- 按一下 [Add label] (新增標籤)。
- 輸入鍵和值。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
- 如要更新標籤,請修改現有的鍵或值。
- 如要儲存變更,請按一下「更新」。
SQL
使用 ALTER SCHEMA SET OPTIONS
DDL 陳述式設定現有資料集的標籤。設定標籤會覆寫資料集中的任何現有標籤。以下範例會在資料集 mydataset
上設定標籤:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
如要在現有資料集中加入標籤,請發出 bq update
指令並搭配使用 set_label
旗標。重複使用該標記即可加入多個標籤。
如果資料集位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集:PROJECT_ID:DATASET
。
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
更改下列內容:
KEY:VALUE
:您要加入的標籤的鍵/值組合。鍵不得重複。鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼,且可使用國際字元。PROJECT_ID
:您的專案 ID。DATASET
:您要加入標籤的資料集。
範例:
如要加入標籤以追蹤部門,請輸入 bq update
指令並指定 department
做為標籤鍵。例如,如要在預設專案中為 mydataset
加入 department:shipping
標籤,請輸入:
bq update --set_label department:shipping mydataset
如要在資料集中加入多個標籤,請重複使用 set_label
旗標並為每個標籤指定專屬鍵。例如,將 department:shipping
標籤和 cost_center:logistics
標籤加入預設專案中的 mydataset
,請輸入:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
如要在現有資料集中加入標籤,請呼叫 datasets.
方法,然後填入資料集資源的 labels
屬性。
由於 datasets.update
方法會取代整個資料集資源,因此建議使用 datasets.
方法。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
這個範例使用 Java 專用 Google HTTP 用戶端程式庫,將要求傳送至 BigQuery API。
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
為資料表和檢視表新增標籤
本頁面說明如何在現有資料表或視圖中加入標籤。如要進一步瞭解如何在建立資料表或檢視表時加入標籤,請參閱建立資料表或建立檢視表。
由於系統會將檢視表當做資料表資源處理,因此可以使用 tables.
方法來修改檢視表和資料表。
必要的 IAM 角色
如要取得在現有資料表或檢視畫面中新增標籤所需的權限,請向管理員要求授予您 BigQuery 資料編輯者 (roles/bigquery.dataEditor
) 身分與存取權管理角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色具備在現有資料表或視圖中加入標籤所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
如要在現有資料表或檢視表中加入標籤,您必須具備下列權限:
bigquery.tables.update
bigquery.tables.get
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
在資料表或檢視表中加入標籤
如何在現有資料表或視圖中加入標籤:
主控台
在 Google Cloud 控制台中選取資料表或檢視表。
按一下 [Details] (詳細資料) 分頁標籤。
按一下「Labels」(標籤) 右側的鉛筆圖示。
在「Edit labels」(編輯標籤) 對話方塊中:
- 按一下 [Add label] (新增標籤)。
- 輸入鍵/值以加入標籤。如要套用其他標籤,請按一下 [Add Label] (新增標籤)。每個資料集中的每個鍵都只能使用一次,但您可以在同一項專案的不同資料集中使用同一個鍵。
- 修改現有的鍵/值以更新標籤。
- 按一下 [Update] (更新),儲存您所做的變更。
SQL
請使用 ALTER TABLE SET OPTIONS
DDL 陳述式設定現有資料表的標籤,或是使用 ALTER VIEW SET OPTIONS
DDL 陳述式設定現有視圖的標籤。設定標籤會覆寫資料表或檢視表上的任何現有標籤。以下範例會在資料表 mytable
上設定兩個標籤:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels = [('department', 'shipping'), ('cost_center', 'logistics')]);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
如要在現有資料表或檢視表中加入標籤,請發出 bq update
指令並搭配使用 set_label
旗標。如要加入多個標籤,請重複使用該標記。
如果資料表或檢視表位於預設專案以外的專案中,請使用下列格式將專案 ID 新增至資料集:project_id:dataset
。
bq update \ --set_label KEY:VALUE \ PROJECT_ID:DATASET.TABLE_OR_VIEW
更改下列內容:
KEY:VALUE
:您要加入的標籤的鍵/值組合。鍵不得重複。鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼,且可使用國際字元。PROJECT_ID
:您的專案 ID。DATASET
:您要加入標籤的資料表或檢視表所屬的資料集。TABLE_OR_VIEW
:您要加入標籤的資料表或檢視表名稱。
範例:
如要加入可追蹤部門的資料表標籤,請輸入 bq update
指令並指定 department
做為標籤鍵。例如,如要在預設專案中為 mytable
加入 department:shipping
標籤,請輸入:
bq update --set_label department:shipping mydataset.mytable
如要加入可追蹤部門的檢視表標籤,請輸入 bq update
指令並指定 department
做為標籤鍵。例如,如要在預設專案中為 myview
加入 department:shipping
標籤,請輸入:
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.
方法,然後填入資料集資源的 labels
屬性。
由於系統會將檢視表當做資料表資源處理,因此可以使用 tables.
方法來修改檢視表和資料表。
由於 tables.update
方法會取代整個資料集資源,因此建議使用 tables.
方法。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
這個範例使用 Java 專用 Google HTTP 用戶端程式庫,將要求傳送至 BigQuery API。
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
為工作新增標籤
您可以透過指令列使用 bq 指令列工具的 --label
旗標,為查詢工作加入標籤。bq 工具僅支援在查詢工作中加入標籤。
如果某個工作是透過 API 提交,您也可以在其中加入標籤,方法是當您呼叫 jobs.insert
方法時,在工作設定中指定 labels
屬性。API 可用於在任何工作類型中加入標籤。
您無法在待處理、執行中或已完成的工作中加入或更新標籤。
在工作中加入標籤後,標籤就會納入您的帳單資料中。
必要的 IAM 角色
如要取得工作所需的權限,請向管理員要求授予您 BigQuery 使用者 (roles/bigquery.user
) 身分與存取權管理角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色包含 bigquery.jobs.create
權限,這是在工作中加入標籤所需的權限。
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
在工作中加入標籤
如何在工作中加入標籤:
bq
如要在查詢工作中加入標籤,請發出 bq query
指令並搭配使用 --label
旗標。如要加入多個標籤,請重複使用該標記。標記表示您的查詢採用 GoogleSQL 語法。
bq query --label KEY:VALUE 'QUERY'
更改下列內容:
KEY:VALUE
:您要在查詢工作中加入的標籤鍵/值組合。鍵不得重複。鍵和值只能包含小寫英文字母、數字字元、底線和破折號。所有字元都必須使用 UTF-8 編碼,且可使用國際字元。如要在查詢工作中加入多個標籤,請重複使用--label
旗標並為每個標籤指定專屬鍵。QUERY
:有效的 GoogleSQL 查詢。
範例:
如要在查詢工作中加入標籤,請輸入:
bq query \
--label department:shipping \
\
'SELECT
column1, column2
FROM
`mydataset.mytable`'
如要在查詢工作中加入多個標籤,請重複使用 --label
旗標並為每個標籤指定專屬鍵。例如,如要在查詢工作中加入 department:shipping
標籤和 cost_center:logistics
標籤,請輸入:
bq query \
--label department:shipping \
--label cost_center:logistics \
\
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
如要在工作中加入標籤,請呼叫 jobs.insert
方法,然後填入工作設定的 labels
屬性。您可以使用 API 在任何類型的工作中加入標籤。
將工作階段中的作法與標籤建立關聯
如果您要在工作階段中執行查詢,可以使用 BigQuery 多語句查詢,為工作階段中的所有未來查詢工作指派標籤。
SQL
執行以下查詢,在工作階段中設定 @@query_label
系統變數:
SET @@query_label = "KEY:VALUE";
- KEY:VALUE:標籤的鍵/值組合,用於指派給工作階段中的所有後續查詢。您也可以新增多個鍵/值組合,並以半形逗號 (例如
SET @@query_label = "key1:value1,key2:value2"
) 分隔。鍵不得重複。鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼,且可使用國際字元。
範例:
SET @@query_label = "cost_center:logistics";
API
如要在使用 API 呼叫執行查詢時,在工作階段中為查詢工作新增標籤,請呼叫 jobs.insert
方法,然後為 connectionProperties
工作設定填入 query_label
屬性。
將查詢標籤與工作階段建立關聯,並在工作階段中執行查詢後,您就可以收集該查詢標籤的查詢稽核記錄。詳情請參閱 BigQuery 稽核記錄參考資料。
為預留項目加上標籤
在預訂資訊中加入標籤後,標籤就會列入帳單資料中。您可以使用標籤篩選 Cloud Billing 資料中的分析時段歸因 SKU。
如要進一步瞭解如何在帳單資料中使用標籤,請參閱「使用篩選器精細化資料」一文。
必要的 IAM 角色
如要取得新增預留空間標籤所需的權限,請要求管理員在管理專案中授予您 BigQuery 資源編輯者 (roles/bigquery.resourceEditor
) 身分與存取權管理角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色包含 bigquery.reservations.update
權限,這是為預訂項目新增標籤所需的權限。
為預留項目加上標籤
如何為預訂資訊加上標籤:
SQL
如要在預訂資訊中加入標籤,請使用 ALTER RESERVATION SET OPTIONS
DDL 陳述式。設定標籤會覆寫預留項目上的任何現有標籤。以下範例會在預留項目 myreservation
上設定標籤:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
ALTER RESERVATION myreservation SET OPTIONS ( labels = [('sensitivity', 'high')]);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
如要在預訂中加入標籤,請發出 bq update
指令並搭配使用 set_label
旗標和 --reservation
旗標。如要加入多個標籤,請重複使用 set_label
標記。
bq update --set_label KEY:VALUE --reservation RESERVATION_NAME
更改下列內容:
KEY:VALUE
:您要加入預訂的標籤的鍵/值組合。鍵不得重複。鍵和值只能包含小寫英文字母、數字字元、底線和破折號。所有字元都必須使用 UTF-8 編碼,且可使用國際字元。如要在預訂中加入多個標籤,請重複使用--set_label
旗標,並為每個標籤指定專屬鍵。RESERVATION_NAME
:保留項目的名稱。
新增不含值的標籤
包含具有空白值的鍵的標籤有時稱為標記。請勿將這項資源與標記資源混淆。詳情請參閱「標籤和標記」。您可以建立不含任何值的新標籤,或是從現有標籤鍵移除值。
如果您要為資源加上標籤,但不需要使用鍵/值格式,則標籤不含值的情況就很實用。舉例來說,如果資料表包含由多個群組 (支援或開發等) 使用的測試資料,您可以在該資料表中加入 test_data
標記以供識別。
如要新增沒有值的標籤,請按照下列步驟操作:
主控台
在 Google Cloud 控制台中,選取適當的資源 (資料集、資料表或檢視表)。
如果是資料集,「Dataset Details」(資料集詳細資料) 頁面會自動開啟;如果是資料表和資料檢視,請按一下 [Details] (詳細資料) 以開啟詳細資料頁面。
在「Details」(詳細資料) 頁面中,按一下「Labels」(標籤) 右側的鉛筆圖示。
在「Edit labels」(編輯標籤) 對話方塊中:
- 按一下 [Add label] (新增標籤)。
- 輸入新的鍵並將值留空。如要套用其他標籤,請按一下「Add label」,並重複執行相同步驟。
- 如要儲存變更,請按一下「更新」。
SQL
如要新增沒有值的標籤,請使用 ALTER TABLE SET OPTIONS
DDL 陳述式:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
如要在現有資源中加入沒有值的標籤,請使用 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.
方法或 tables.
方法,並在資料集資源或資料表資源中加入值設為空字串 (""
) 的標籤。您可以將現有標籤的值替換為空字串,藉此移除標籤的值。
由於系統會將檢視表當做資料表資源處理,因此可以使用 tables.
方法來修改檢視表和資料表。此外,因為 tables.update
方法會取代整個資料集資源,因此建議使用 tables.
方法。
後續步驟
- 瞭解如何在 BigQuery 資源中查看標籤。
- 瞭解如何在 BigQuery 資源中更新標籤。
- 瞭解如何使用標籤篩選資源。
- 瞭解如何在 BigQuery 資源中刪除標籤。
- 閱讀 Resource Manager 說明文件中的使用標籤相關說明。