管理工作機會
本文件說明如何在 BigQuery 中管理工作,包括如何查看工作詳細資料、列出工作、取消工作、重複執行工作,以及刪除工作中繼資料。
關於 BigQuery 工作
每次您載入、匯出、查詢或複製資料時,BigQuery 都會自動建立、排定及執行工作,以便追蹤任務的進度。
因為工作可能需要長時間才能完成,所以會非同步執行,而且可以輪詢其狀態。執行時間較短的動作 (如列出資源或取得中繼資料) 不會以工作形式管理。
提交工作時,可能會有下列其中一種狀態:
PENDING
:已排定工作並等待執行。RUNNING
:工作正在進行中。DONE
:工作已完成。如果工作完成且沒有錯誤,BigQuery 會將此狀態回報為SUCCESS
。如果工作完成時發生錯誤,BigQuery 會將此狀態回報為FAILURE
。
配額
如要瞭解工作配額,請參閱「配額與限制」頁面中工作類型的說明文件:
定價
每個工作都與您指定的特定專案相關聯。因工作而產生的任何使用量,均會向連接相關專案的帳單帳戶收取費用。如果您分享專案的存取權,則在該專案中執行的任何工作也會向帳單帳戶收費。
舉例來說,執行查詢工作時,系統會向執行該工作的專案收取費用。因此,當您查看查詢工作以 <project_id>:<region>.<job_id>
格式顯示的工作 ID 時,project_id
就是該查詢所產生費用的專案 ID。
詳情請參閱「定價」。
事前準備
授予 Identity and Access Management (IAM) 角色,為使用者提供執行本文中各項工作的必要權限。
必要的角色
如要取得執行及管理工作所需的權限,請要求管理員為您授予專案的下列 IAM 角色:
-
執行或重複執行工作、列出工作、查看工作詳細資料,以及取消工作:
BigQuery 工作使用者 (
roles/bigquery.jobUser
) 或 BigQuery 使用者 (roles/bigquery.user
) -
列出專案中的所有工作:
BigQuery 管理員 (
roles/bigquery.admin
) 或 BigQuery 資源管理員 (roles/bigquery.resourceAdmin
) -
查看專案中所有工作的詳細資料、取消專案中的任何工作,以及刪除工作中繼發資料:
BigQuery 管理員 (
roles/bigquery.admin
)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這些預先定義的角色包含執行及管理工作所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
如要執行及管理工作,您必須具備下列權限:
-
執行或重複工作,並列出工作:
bigquery.jobs.create
-
查看工作詳細資料:
bigquery.jobs.get
-
取消工作:
bigquery.jobs.update
-
查看專案中所有工作的詳細資料:
-
bigquery.jobs.get
-
bigquery.jobs.listAll
-
-
列出專案中的所有工作:
bigquery.jobs.listAll
-
取消專案中的任何工作:
-
bigquery.jobs.update
-
bigquery.jobs.listAll
-
-
刪除工作中繼資料:
-
bigquery.jobs.delete
-
bigquery.jobs.listAll
-
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
查看工作詳細資料
您可以使用 Google Cloud 主控台、bq 指令列工具、API 或用戶端程式庫查看工作詳細資料。詳細資料包括資料和中繼資料,例如工作類型、工作狀態,以及建立工作的使用者。
如要查看工作詳細資料,請按照下列步驟操作:
主控台
前往「BigQuery」頁面
展開「工作記錄」窗格。
選取要查看的工作記錄類型:
- 如要顯示近期工作的資訊,請按一下「Personal history」。
- 如要顯示專案中近期工作的資訊,請按一下「Project history」(專案記錄)。
如要查看工作詳細資料,請按一下工作。
bq
發出 bq show
指令並搭配使用 --job=true
標記和工作 ID。
當您提供工作 ID 時,可以使用完整 ID 或簡短格式。舉例來說, Google Cloud 控制台列出的工作 ID 是完整 ID,也就是包含專案 ID 和位置:
my-project-1234:US.bquijob_123x456_123y123z123c
在指令列工具中列出的工作 ID 採用簡短格式。不含專案 ID 和位置:
bquijob_123x456_123y123z123c
如要指定工作位置,請提供 --location
標記,並將值設為您的位置。如果您使用完整工作 ID,則不一定要提供標記。如果您加入 --location
標記且使用的是完整工作 ID,則系統會忽略 --location
標記。
以下指令要求工作的相關資訊:
bq --location=LOCATION show --job=true JOB_ID
更改下列內容:
LOCATION
:執行工作的位置名稱。舉例來說,如果您在東京地區使用 BigQuery,請將該旗標的值設為asia-northeast1
。您可以使用.bigqueryrc
檔案設定位置的預設值。如果未在工作 ID 中指定位置或使用--location
標記,系統會使用預設位置。JOB_ID
:工作 ID
範例
下列指令可取得在 myproject
中執行的 US.bquijob_123x456_123y123z123c
工作摘要資訊:
bq show --job=true myproject:US.bquijob_123x456_123y123z123c
輸出結果會與下列內容相似:
Job Type State Start Time Duration User Email Bytes Processed Bytes Billed Billing Tier Labels ---------- --------- ----------------- ---------- ------------------- ----------------- -------------- -------------- -------- extract SUCCESS 06 Jul 11:32:10 0:01:41 user@example.com
如要查看完整的工作詳細資料,請輸入:
bq show --format=prettyjson --job=true myproject:US.bquijob_123x456_789y123z456c
輸出結果會與下列內容相似:
{ "configuration": { "extract": { "compression": "NONE", "destinationUri": "[URI removed]", "destinationUris": [ "[URI removed]" ], "sourceTable": { "datasetId": "github_repos", "projectId": "bigquery-public-data", "tableId": "commits" } } }, "etag": "\"[etag removed]\"", "id": "myproject:bquijob_123x456_789y123z456c", "jobReference": { "jobId": "bquijob_123x456_789y123z456c", "projectId": "[Project ID removed]" }, "kind": "bigquery#job", "selfLink": "https://bigquery.googleapis.com/bigquery/v2/projects/federated-testing/jobs/bquijob_123x456_789y123z456c", "statistics": { "creationTime": "1499365894527", "endTime": "1499365894702", "startTime": "1499365894702" }, "status": { "errorResult": { "debugInfo": "[Information removed for readability]", "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" }, "errors": [ { "message": "Operation cannot be performed on a nested schema. Field: author", "reason": "invalid" } ], "state": "DONE" }, "user_email": "user@example.com" }
API
呼叫 jobs.get,並提供 jobId
和 projectId
參數。(選用) 提供 location
參數,並將值設為執行工作的位置。如果您使用包含該位置的完整工作 ID (例如 my-project-1234:US.bquijob_123x456_123y123z123c
),就不一定要提供這項參數。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如需更多工作排解資訊,請參閱 INFORMATION_SCHEMA.JOBS*
檢視畫面和記錄。
列出工作
BigQuery 會為專案的所有工作和所有位置儲存六個月的工作歷史記錄。工作記錄包含處於「RUNNING
」狀態的工作,以及已經「DONE
」(從回報的「SUCCESS
」或「FAILURE
」狀態來判斷) 的工作。
如要列出專案中的工作,請按照下列步驟操作:
主控台
前往「BigQuery」頁面
展開「工作記錄」窗格。
如要列出專案中的所有工作,請按一下「Project history」。如果您不是專案擁有者,可能沒有查看專案中所有工作的權限。最新的工作會列在最前面。
如要查看工作清單,請按一下「Personal history」。
bq
發出 bq ls
指令並搭配使用下列其中一個標記:
--jobs=true
或-j
:將工作識別為要列出的資源類型。--all=true
或-a
:列出所有使用者的工作。您必須具備bigquery.jobs.listAll
權限,才能查看所有工作的完整 (未遮蓋的) 詳細資料。--min_creation_time
:列出在已提供的時間戳記值之後的工作。這個值以 Unix 紀元時間戳記的形式以毫秒為單位表示。--max_creation_time
:列出在所提供時間戳記值之前的工作。這個值以 Unix 紀元時間戳記表示,以毫秒為單位。--max_results
或-n
可限制結果數。預設值為 50 個結果。
bq ls --jobs=true --all=true \ --min_creation_time=MIN_TIME \ --max_creation_time=MAX_TIME \ --max_results=MAX_RESULTS \ PROJECT_ID
更改下列內容:
MIN_TIME
:整數,代表以毫秒為單位的 Unix Epoch 紀元時間戳記。MAX_TIME
:整數,代表以毫秒為單位的 Unix Epoch 紀元時間戳記。MAX_RESULTS
:整數,指出傳回的工作數。PROJECT_ID
:專案 ID,該專案含有您要列出的工作。如果您設定預設專案,則不需要提供PROJECT_ID
參數。
範例
以下指令會列出當前使用者的所有工作。執行這個指令需要 bigquery.jobs.list
權限。
bq ls --jobs=true myproject
以下指令會列出所有使用者的全部工作。執行這個指令需要 bigquery.jobs.listAll
權限。
bq ls --jobs=true --all=true myproject
以下指令會列出 myproject
中 10 個最新的工作:
bq ls --jobs=true --all=true --max_results=10 myproject
以下指令會列出在 2032 年 3 月 3 日上午 4 點 4 分之前提交的所有工作。這個時間戳記 (以毫秒為單位) 等於下列整數值:1961899440000
。
bq ls --jobs=true --max_creation_time=1961899440000
API
呼叫 jobs.list
方法,並提供 projectId
參數。如要列出所有使用者的工作,請將 allUsers
參數設為 true
。您必須具備 bigquery.jobs.listAll
權限,才能將 allUsers
設為 true
。jobs.list
方法不會傳回子工作。如要列出子項工作,請使用 INFORMATION_SCHEMA.JOBS
檢視畫面。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
取消工作
您可以取消 RUNNING
或 PENDING
工作。取消作業通常不到一分鐘即可完成。
即使是可以取消的工作,也不保證一定能成功取消。工作可能在提交取消要求時剛好完成,或工作也可能處於無法取消的階段。
如要取消工作,請按照下列步驟操作:
主控台
前往「BigQuery」頁面
按一下「Compose new query」(撰寫新查詢),然後輸入查詢。
點選「執行」執行查詢。
如要取消工作,請按一下「取消」。
SQL
使用 BQ.JOBS.CANCEL
系統程序:
CALL BQ.JOBS.CANCEL('JOB_ID');
將 JOB_ID 替換為要取消的工作 ID。
如果您位於其他專案,但與要取消的工作位於相同的區域,則必須一併提供專案 ID:
CALL BQ.JOBS.CANCEL('PROJECT_ID.JOB_ID');
更改下列內容:
PROJECT_ID
:含有您要取消的工作的專案 IDJOB_ID
:您要取消的工作 ID
程序會立即傳回,而 BigQuery 會在稍後取消該工作。如果工作已成功或失敗,程序就不會生效。
bq
發出含有 JOB_ID
引數的 bq cancel
指令。您可以使用 --nosync=true
標記要求取消並立即傳回。根據預設,取消要求會等待完成。
當您提供 JOB_ID
引數時,可以使用完整 ID 或簡短格式。舉例來說, Google Cloud 控制台列出的工作 ID 是完整 ID,也就是包含專案 ID 和位置:
my-project-1234:US.bquijob_123x456_123y123z123c
在 bq 指令列工具中列出的工作 ID 採用簡短格式,不包含專案 ID 和位置:
bquijob_123x456_123y123z123c
如要指定工作位置,請提供 --location
標記,並將值設為您的位置。如果您使用完整工作 ID,則不一定要提供標記。如果您加入 --location
標記且使用的是完整工作 ID,則系統會忽略 --location
標記。
以下指令會要求取消工作並等待完成。如果提供完整工作 ID,則系統會忽略 --location
標記:
bq --location=LOCATION cancel JOB_ID
以下指令會要求取消工作並立即傳回。如果提供完整工作 ID,則系統會忽略 --location
標記:
bq --location=LOCATION --nosync cancel JOB_ID
更改下列內容:
LOCATION
(選用):執行工作的位置名稱。舉例來說,如果您在東京地區使用 BigQuery,請將該旗標的值設為asia-northeast1
。您可以使用.bigqueryrc
檔案設定位置的預設值。JOB_ID
:您要取消的工作 ID。如果您從 Google Cloud 控制台複製工作 ID,則專案 ID 和位置會併入工作 ID 中;例如:my-project-1234:US.bquijob_123x456_123y123z123c
。
範例
以下指令會取消在 my-project-1234
專案的 US
多地區位置執行的 my-project-1234:US.bquijob_123x456_123y123z123c
工作,並等待完成。因為使用的是完整工作 ID,所以未提供 location 標記。
bq cancel my-project-1234:US.bquijob_123x456_123y123z123c
以下指令會取消在 my-project-1234
專案的 US
多地區位置執行的 bquijob_123x456_123y123z123c
工作,並等待完成。因為使用的是簡短格式的工作 ID,所以提供了 --location
標記。
bq --location=US cancel bquijob_123x456_123y123z123c
以下指令會取消在 my-project-1234
專案的 US
多地區位置執行的 bquijob_123x456_123y123z123c
工作,並立即傳回。因為使用的是完整工作 ID,所以未提供 --location
標記。
bq --nosync cancel my-project-1234:US.bquijob_123x456_123y123z123c
API
呼叫 jobs.get,並提供 jobId
和 projectId
參數。提供 location
參數,並將值設為執行工作的位置。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
刪除工作中繼資料
您可以使用 bq 指令列工具和 Python 用戶端程式庫,刪除特定工作的中繼資料。BigQuery 會保留過去 6 個月內執行的工作記錄。您可以使用這個方法,移除可能出現在查詢陳述式中的機密資訊。工作中繼資料只能在工作完成後刪除。如果工作已建立子項工作,系統也會刪除子項工作。系統不允許刪除子項工作。只能刪除父項或頂層工作。
如要刪除工作中繼資料,請按照下列步驟操作:
bq
發出 bq rm
指令並搭配使用 -j
標記和工作 ID。
當您提供工作 ID 時,可以使用完整 ID 或簡短格式。舉例來說, Google Cloud 控制台列出的工作 ID 是完整 ID,也就是包含專案 ID 和位置:
my-project-1234:US.bquijob_123x456_123y123z123c
在 bq 指令列工具中列出的工作 ID 採用簡短格式。不含專案 ID 和位置:
bquijob_123x456_123y123z123c
如要指定工作位置,請提供 --location
標記,並將值設為您的位置。如果您使用完整工作 ID,則不一定要提供標記。如果您加入 --location
標記且使用的是完整工作 ID,則系統會忽略 --location
標記。
以下指令會刪除工作:
bq --location=location \ --project_id=project_id \ rm -j job_id
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
重複工作
系統無法使用相同的工作 ID 重複執行工作,因此您必須使用相同的設定建立新工作。您可以在Google Cloud 主控台或 bq 指令列工具中提交新工作,系統會指派新的工作 ID。如果您使用 API 或用戶端程式庫來提交工作,則必須產生新的工作 ID。
如要重複執行工作,請按照下列步驟操作:
主控台
如要重複執行查詢工作,請按照下列步驟操作:
前往「BigQuery」頁面
展開「工作記錄」窗格。
如要列出所有工作,請按一下「Personal history」(個人記錄)。如要列出專案中的所有工作,請按一下「專案記錄」。
按一下查詢工作,即可開啟工作詳細資料。
如要重複查詢,請按一下「開啟為新的查詢」。
按一下「執行」。
如要重複執行載入工作,請按照下列步驟操作:
前往「BigQuery」頁面
展開「工作記錄」窗格。
如要列出所有工作,請按一下「Personal history」(個人記錄)。如要列出專案中的所有工作,請按一下「專案記錄」。
按一下載入工作,即可開啟工作詳細資料。
如要重複執行工作,請按一下「Repeat load job」。
bq
重新發出指令,BigQuery 會自動產生具有新工作 ID 的工作。
API
沒有可以重複執行工作的一次呼叫方法;如要重複特定工作,請執行下列步驟:
呼叫
jobs.get
以擷取重複執行工作時所需的資源。移除「id」、「status」和「statistics」欄位。 將「jobId」 欄位更改為用戶端程式碼產生的新值。視需要更改任何其他欄位。
使用修改後的資源和新的工作 ID 呼叫
jobs.insert
,以啟動新工作。
後續步驟
- 瞭解如何透過程式執行工作。