遷移至 Cloud Tasks 用戶端程式庫前,請先參閱遷移總覽。
升級至 Cloud Tasks 用戶端程式庫
如果您想完全停用舊版隨附服務,可以遷移程式碼,直接使用 Cloud Tasks API。這需要重構應用程式程式碼。
Cloud Tasks 提供的服務與工作佇列 RPC API 相同。也就是說,您不必重新建立現有的發送佇列和推送工作。不過,您必須遷移建立或與發送佇列或推送工作互動的程式碼,才能使用 Cloud Tasks API。
您可以使用 Cloud Tasks REST 和 RPC API、Cloud Tasks 用戶端程式庫、Google Cloud CLI 和 Google Cloud 控制台,建立及與發送佇列和任務互動。本頁提供使用 gcloud CLI 和 Cloud Tasks 用戶端程式庫的範例。
Cloud Tasks 不支援的功能
如要遷移 Cloud Tasks 用戶端程式庫,請注意 Cloud Tasks 不支援下列功能:
- 在 Datastore 交易中將工作排入佇列
- 使用延遲工作程式庫,而非 worker 服務
- 在多用戶群應用程式中處理工作
- 使用本機開發伺服器進行模擬
- 非同步新增工作
或者,如果您升級至最新版 SDK,則可透過 SDK 包裝函式支援延遲工作、命名空間和本機模擬等功能。
定價與配額
將發送佇列遷移至 Cloud Tasks,可能會影響應用程式的定價和配額。
定價
遷移前,請先查看 Cloud Tasks 定價,估算每月費用。
與工作佇列類似,使用 Cloud Tasks 推送目標將要求傳送至 App Engine 應用程式不需付費。不過,與工作佇列不同的是,Cloud Tasks 會針對執行的作業 (例如建立、刪除或管理工作) 收費。與免費的 App Engine 工作佇列相比,這可能會導致每月總費用較高。
配額
Cloud Tasks 要求也會計入 App Engine 要求配額。
與工作佇列一樣,Cloud Tasks 也有服務專屬配額。遷移至 Cloud Tasks 可能會變更配額。
事前準備
以下各節將說明將發送佇列遷移至 Cloud Tasks 之前的設定步驟。
遷移提取佇列
開始之前,請先遷移提取佇列,再按照本指南的操作說明遷移發送佇列。不建議在遷移發送佇列後遷移提取佇列,因為必須使用 queue.yaml 檔案,可能會導致 Cloud Tasks 發生非預期的行為。
保護佇列設定
開始遷移至 Cloud Tasks 後,修改 queue.yaml 檔案可能會導致非預期的行為,因此不建議這麼做。請按照下列步驟操作,防止 queue.yaml 檔案修改佇列設定。
設定 gcloud CLI,在日後的部署作業中省略
queue.yaml檔案。將
queue.yaml檔案新增至.gcloudignore檔案。如要檢查是否已有.gcloudignore檔案,請在終端機中,從應用程式的頂層目錄執行下列指令。如果檔案存在,這個指令會輸出檔案名稱。ls -a | grep .gcloudignore
如要進一步瞭解
.gcloudignore檔案,請參閱.gcloudignore參考資料。限制
queue.yaml檔案的權限。請按照保護佇列設定指南中的最佳做法操作。
瞭解 Cloud Tasks 和
queue.yaml檔案 (選用)。使用 Cloud Tasks API 管理佇列設定時,部署
queue.yaml檔案會覆寫 Cloud Tasks 設定,可能導致非預期的行為。詳情請參閱「使用佇列管理與 queue.yaml」。
向 Cloud Tasks API 驗證應用程式
您必須向 Cloud Tasks API 驗證應用程式。本節將討論兩種不同用途的驗證。
如要在本機開發或測試應用程式,建議使用服務帳戶。如需設定服務帳戶並連結至應用程式的操作說明,請參閱「手動取得及提供服務帳戶憑證」。
如要在 App Engine 上部署應用程式,您不需要提供任何新的驗證。應用程式預設憑證 (ADC) 會推論 App Engine 應用程式的驗證詳細資料。
匯入 Cloud 用戶端程式庫
如要搭配 App Engine 應用程式使用 Cloud Tasks 用戶端程式庫,請按照下列步驟操作:
使用 Composer 安裝 Cloud Tasks 用戶端程式庫依附元件:
composer require google/cloud-tasks在負責建立工作並將工作排入佇列的檔案中,匯入 Cloud Tasks 用戶端程式庫類別:
use Google\Cloud\Tasks\V2\AppEngineHttpRequest; use Google\Cloud\Tasks\V2\Client\CloudTasksClient; use Google\Cloud\Tasks\V2\CreateTaskRequest; use Google\Cloud\Tasks\V2\HttpMethod; use Google\Cloud\Tasks\V2\Task;
建立及管理佇列
本節說明如何使用 Cloud Tasks API 建立及管理佇列。
使用 Cloud Tasks 時,您不必透過 queue.yaml 檔案建立或管理佇列。而是使用 Cloud Tasks API。不建議同時使用 queue.yaml 檔案和 Cloud Tasks API,但視應用程式而定,從工作佇列遷移至 Cloud Tasks 時,可能無法避免這種情況。請參閱「使用佇列管理與 queue.yaml」一文,瞭解最佳做法。
建立佇列
如果您的應用程式會以程式輔助方式建立佇列,或您想透過指令列建立其他佇列,請參閱本節。
在 Cloud Tasks 中,佇列名稱的格式為 projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID。佇列名稱的 LOCATION_ID 部分對應至 Google Cloud 區域。佇列名稱的 QUEUE_ID 部分等同於工作佇列佇列 name 欄位。建立佇列時,系統會根據您指定的專案、區域和 QUEUE_ID 產生佇列名稱。
一般來說,佇列位置 (即區域) 必須與應用程式的區域相同。這項規則有兩個例外狀況,分別是使用 europe-west 區域的應用程式,以及使用 us-central 區域的應用程式。在 Cloud Tasks 中,這些區域分別稱為 europe-west1 和 us-central1。
您可以在建立佇列時指定選用的佇列設定,也可以在建立佇列後更新佇列。
您不必重新建立現有佇列。請改為閱讀本指南的相關部分,遷移與現有佇列互動的程式碼。
重複使用佇列名稱
刪除佇列後,必須等待 7 天,才能在相同專案和位置 (即區域) 中,建立具有相同佇列 ID 的佇列。
以下範例會使用 Cloud Tasks 建立兩個佇列。第一個佇列的佇列 ID 為 queue-blue,並設定為以 5/s 的速率將所有工作傳送至服務 task-module 的 v2 版本。第二個佇列的佇列 ID 為 queue-red,並以 1/s 的速率調度任務。兩者都是在專案 ID 為 my-project-id 的專案中建立,位置為 us-central1。這相當於在 Cloud Tasks 的工作佇列中建立佇列。
gcloud
gcloud CLI 會從 gcloud CLI 設定推斷專案和位置。
gcloud tasks queues create queue-blue \ --max-dispatches-per-second=5 \ --routing-override=service:task-module,version:v2
gcloud tasks queues create queue-red \ --max-dispatches-per-second=1
詳情請參閱 Cloud Tasks 參考資料「建立 Cloud Tasks 佇列」。
設定佇列處理率
下表列出 Task Queues 和 Cloud Tasks 之間不同的欄位。
| 「Task Queues」(工作佇列) 欄位 | Cloud Tasks 欄位 | 說明 |
|---|---|---|
rate |
max_dispatches_per_second |
從佇列調度任務的速率上限 |
max_concurrent_requests |
max_concurrent_dispatches |
可從佇列調度的並行任務數量上限 |
bucket_size |
max_burst_size |
Cloud Tasks 會根據
如果是使用 |
total_storage_limit |
Cloud Tasks 中已淘汰 | Cloud Tasks 不支援設定自訂儲存空間限制 |
您可以在建立佇列時設定佇列處理率,或在建立後更新。以下範例使用 Cloud Tasks,在已建立的 queue-blue 佇列上設定處理速率。如果 queue-blue 是使用 queue.yaml 檔案建立或設定,下列範例會根據 20 的 max_dispatches_per_second 值重設 max_burst_size。這相當於在工作佇列中設定佇列處理速率。
gcloud
gcloud tasks queues update queue-blue \ --max-dispatches-per-second=20 \ --max-concurrent-dispatches=10
詳情請參閱「定義頻率限制」。
停用及重新啟用佇列
Cloud Tasks 使用「暫停」一詞的方式,與工作佇列使用「停用」一詞的方式相同。暫停佇列後,佇列中的任務會停止執行,直到佇列恢復為止。不過,您仍可繼續將工作新增至已暫停的佇列。Cloud Tasks 使用「resume」一詞的方式與工作佇列相同。
下列範例會暫停 ID 為 queue1 的佇列。這相當於在 Task Queues 中停用佇列。
gcloud
gcloud tasks queues pause queue1
詳情請參閱 Cloud Tasks 參考資料「暫停佇列」。
刪除佇列
刪除佇列後,必須等待 7 天,才能建立同名佇列。如果無法等待 7 天,建議您清除佇列中的所有任務,並重新設定佇列。
下列範例會刪除 ID 為 queue1 的佇列。這相當於在 Task Queues 中刪除佇列。
gcloud
gcloud tasks queues delete queue1
詳情請參閱 Cloud Tasks 參考資料「刪除佇列」。
建立及管理工作
本節說明如何使用 Cloud Tasks API 建立及管理任務。
建立工作
下表列出 Task Queues 和 Cloud Tasks 之間不同的欄位。
| 「Task Queues」(工作佇列) 欄位 | Cloud Tasks 欄位 | 說明 |
|---|---|---|
| 不適用 | app_engine_http_request |
建立指定 App Engine 服務的要求。這類工作稱為 App Engine 工作。 |
method |
http_method |
指定要求方法,例如 POST |
url |
relative_uri |
指定工作處理常式。請注意最後一個字母的差異:i 代表統一資源識別項,而非l 代表統一資源定位器 |
target |
app_engine_routing |
選用。指定 App Engine 工作的 App Engine service、version 和 instance。如未設定,系統會使用預設服務、版本和執行個體。 |
以下範例會建立一項任務,將任務轉送至預設 App Engine 服務上的處理常式 /update_counter。這相當於在 Task Queues 中建立任務。
gcloud
gcloud tasks create-app-engine-task \ --queue=default \ --method=POST \ --relative-uri=/update_counter \ --routing=service:worker \ --body-content=10
詳情請參閱 Cloud Tasks 參考資料「建立 App Engine 工作」。
指定目標服務和轉送
您可以選擇是否為 App Engine 任務指定 App Engine 目標服務、版本和執行個體。根據預設,App Engine 任務會轉送至嘗試執行任務時預設的服務、版本和執行個體。
在建立工作時設定工作的 app_engine_routing 屬性,為工作指定不同的 App Engine 服務、版本或執行個體。
如要將特定佇列中的所有任務轉送至同一個 App Engine 服務、版本和執行個體,您可以在佇列上設定 app_engine_routing_override 屬性。
詳情請參閱 Cloud Tasks 參考資料「設定轉送」。
將資料傳遞至處理常式
與工作佇列一樣,您可以使用 Cloud Tasks,透過兩種方式將資料傳遞至處理常式。您可以將資料做為相對 URI 中的查詢參數傳遞,也可以使用 HTTP 方法 POST 或 PUT 在要求主體中傳遞資料。
Cloud Tasks 使用「body」一詞的方式,與工作佇列使用「payload」一詞的方式相同。在 Cloud Tasks 中,預設的主體內容類型是 octet-stream,而非純文字。您可以在標頭中指定內文內容類型。
以下範例示範如何透過兩種不同方式,將鍵傳遞至處理常式 /update_counter。這相當於 Cloud Tasks 中的將資料傳遞至處理常式。
gcloud
gcloud tasks create-app-engine-task \ --queue=default \ --method=GET \ --relative-uri=/update_counter?key=blue \ --routing=service:worker
gcloud tasks create-app-engine-task \ --queue=default \ --method=POST \ --relative-uri=/update_counter \ --routing=service:worker \ --body-content="{'key': 'blue'}"
指定工作名稱
您可以選擇是否指定工作名稱。如未指定工作名稱,Cloud Tasks 會根據您在建立工作時指定的佇列,產生工作 ID 並推斷專案和位置 (即區域),為您建構工作名稱。
工作名稱的格式為 projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID。工作名稱的 TASK_ID 部分等同於工作佇列工作 name 欄位。
重複使用工作名稱
您必須等待一段時間,才能重複使用任務名稱。您必須等待的時間長度,取決於分派工作的佇列是在 Cloud Tasks 或工作佇列中建立。
如果是使用工作佇列建立的佇列 (包括預設佇列) 中的工作,您必須在原始工作刪除或執行後等待約 9 天。如果是使用 Cloud Tasks 建立的佇列,則必須在原始任務刪除或執行後,等待約 1 小時。
以下範例會建立 TASK_ID 設為 first-try 的任務,並將其新增至預設佇列。這相當於在工作佇列中命名 Cloud Tasks 工作。
gcloud
gcloud CLI 會從設定推斷專案和位置,藉此建構任務名稱。
gcloud tasks create-app-engine-task first-try \ --queue=default \ --method=GET \ --relative-uri=/url/path
重試失敗的工作
您可以在建立或更新佇列時,設定佇列的工作重試設定。下表列出 Task Queues 欄位和對應的 Cloud Tasks 欄位。
| 「Task Queues」(工作佇列) 欄位 | Cloud Tasks 欄位 |
|---|---|
task_retry_limit |
max_attempts |
task_age_limit |
max_retry_duration |
min_backoff_seconds |
min_backoff |
max_backoff_seconds |
max_backoff |
max_doublings |
max_doublings |
使用工作專屬重試參數
在工作佇列中設定的工作專屬重試參數可在 Cloud Tasks 中運作,但您無法編輯這些參數,也無法為新工作設定這些參數。如要變更具有特定重試參數的工作,請使用具有所需重試參數的 Cloud Tasks 佇列重新建立工作。
以下範例示範幾種重試情況:
- 在
fooqueue中,任務最多會重試七次,且重試時間最長為首次執行嘗試後的兩天。如果兩項限制都已超過,這項工作就會永久失敗。 - 在
barqueue中,App Engine 會嘗試重試工作,每次重試之間的間隔會線性增加,直到達到最大輪詢間隔,並以最大間隔無限重試 (因此要求之間的間隔為 10 秒、20 秒、30 秒、...、190 秒、200 秒、200 秒、...)。 - 在
bazqueue中,重試間隔從 10 秒開始,然後加倍三次,接著線性增加,最後以最大間隔無限重試 (因此要求之間的間隔為 10 秒、20 秒、40 秒、80 秒、160 秒、240 秒、300 秒、300 秒...)。
這相當於在工作佇列中重試工作。
gcloud
設定指定秒數的選項時,必須在整數後方加上 s (例如 200s,而非 200)。
gcloud tasks queues create fooqueue \ --max-attempts=7 \ --max-retry-duration=172800s #2*60*60*24 seconds in 2 days
gcloud tasks queues create barqueue \ --min-backoff=10s \ --max-backoff=200s \ --max-doublings=0
gcloud tasks queues create bazqueue \ --min-backoff=10s \ --max-backoff=300s \ --max-doublings=3
詳情請參閱 Cloud Tasks 參考資料「設定重試參數」。
刪除佇列中的任務
刪除工作後,如果工作位於使用 queue.yaml 檔案建立的佇列中,您必須等待 9 天,才能建立同名工作;如果工作位於使用 Cloud Tasks 建立的佇列中,則須等待 1 小時。
下列範例會從佇列 ID 為 queue1 的佇列中,刪除工作 ID 為 foo 的工作。這相當於在工作佇列中刪除工作。
gcloud
工作專案和位置是從 gcloud CLI 預設專案推斷而來。
gcloud tasks delete foo --queue=queue1
詳情請參閱 Cloud Tasks 參考資料「從佇列中刪除工作」。
清除工作
下列範例會清除佇列 ID 為 queue1 的佇列中的所有任務。這相當於在 Task Queues 中清除工作。
gcloud
系統會從 gcloud CLI 預設專案推論佇列專案和位置。
gcloud tasks queues purge queue1
詳情請參閱 Cloud Tasks 參考資料「清除佇列中的所有任務」。