使用 queue.yaml 管理佇列

雖然您可以使用 queue.yaml 檔案管理佇列，但混用佇列管理方法可能會產生非預期的結果。本指南說明混用這些方法的風險，並介紹如何解決常見的設定問題。

Cloud Tasks API 提供獨立於 App Engine 工作佇列服務的介面。您可以使用這個介面，透過 Google Cloud 控制台或 Google Cloud CLI 管理佇列。您可以使用 App Engine SDK (平台專屬 API、獨立工具和執行階段檔案的集合) 存取透過 Cloud Tasks API 建立的佇列，也可以使用 Cloud Tasks API 存取透過 App Engine SDK 建立的佇列。

為維持相容性，您可以使用 App Engine SDK 的設定檔 queue.yaml，為 Cloud Tasks API 建立及設定佇列。不過，使用這個檔案和 Cloud Tasks API 管理佇列可能會導致問題，詳情請參閱本指南。

事前準備

如果您是第一次使用 Cloud Tasks 或 App Engine，請單獨使用 Cloud Tasks API 管理佇列，避免使用 queue.yaml。Cloud Tasks 佇列管理方法可讓您在建立、更新及刪除佇列時有更多選擇。

如果您目前使用 queue.yaml，並且考慮改用 Cloud Tasks 佇列管理方法，請務必先瞭解混用佇列管理方法可能造成的風險。

強制執行佇列管理方法

為避免混用佇列管理方法，您可以建立網頁應用程式或指令列工具，用於建立、更新及刪除佇列。無論該工具使用 Cloud Tasks 佇列管理方法或 queue.yaml，都是使用者不需要瞭解的實作細節。強制使用該工具，即可確保方法不會意外遭到混用。將 Cloud Tasks 佇列管理員 Identity and Access Management (IAM) 角色授予工具，並要求使用者進行驗證。如要進一步瞭解存取權管理，請參閱「安全佇列設定」。

佇列設定延遲

佇列設定變更可能需要幾分鐘才會生效。舉例來說，呼叫 CreateQueue 或 UpdateQueue 後，可能要過幾分鐘，才能在該佇列上成功呼叫 CreateTask。

App Engine default 佇列

在 App Engine SDK 和 Cloud Tasks API 中，名為 default 的 App Engine 佇列會受到特殊處理。

何時會建立 default 佇列？

如果 default 佇列不存在，系統會在下列情況建立佇列：
  • 當初次使用 App Engine SDK 將工作新增到 default 佇列時
  • 上傳指定 default 佇列的 queue.yaml 檔案時
  • 呼叫 CreateQueue 或 UpdateQueue 來建立 default 佇列時
Cloud Tasks 會強制執行哪些限制？

為了保留與 App Engine 的相容性，Cloud Tasks 會強制執行下列有關 default 佇列的限制：
  • Cloud Tasks API 不會自動建立 default 佇列或任何其他佇列
  • 如果建立了名為「defaultdefault」的佇列，該佇列必須是 使用 App Engine 工作的佇列。
  • 如果佇列尚不存在，在 default 佇列上呼叫 GetQueue 會傳回 not found 錯誤。
  • default 佇列建立完成後，才會顯示在 ListQueues 輸出內容中
  • 您可以使用 UpdateQueue 呼叫修改 default 佇列設定
  • default佇列建立後，就無法刪除

混用佇列管理方法的風險

對於基礎服務，queue.yaml 檔案是最終版本。如果上傳的 queue.yaml 檔案省略了專案中的現有佇列，無論這些佇列是如何建立的，都會遭到停用或暫停。舉例來說，如果您使用 Cloud Tasks API 呼叫 CreateQueue 或 UpdateQueue，然後上傳省略這些佇列的 queue.yaml 檔案，這些佇列就會遭到停用。然後恢復已停用的佇列。

混用佇列管理方法可能會導致非預期的行為。舉例來說，請參考下列情境：

情境 1

您會呼叫 CreateQueue 建立名為 cloud-tasks-queue 的佇列，然後上傳 queue.yaml 檔案，其中包含下列內容：

queue:
- name: queue-yaml-queue

這會導致下列佇列狀態：

  • 名為「cloud-tasks-queue」cloud-tasks-queue的佇列以及先前存在的任何其他佇列會處於 DISABLED 狀態。
  • 名為「queue-yaml-queue」的佇列處於 RUNNING 狀態。

情境 2

您使用 Cloud Tasks API 停用佇列，但該佇列隨後出現在上傳的 queue.yaml 檔案中。佇列已恢復運作。

情境 3

您可以使用 DeleteQueue 方法刪除佇列，該佇列稍後會顯示在 queue.yaml 檔案中。queue.yaml上傳作業可能會失敗，因為刪除佇列名稱後，幾天內無法重複使用。

使用稽核記錄進行偵錯

您可以檢查專案的管理員活動稽核記錄，並擷取佇列設定變更記錄，包括佇列建立、更新和刪除作業。

舉例來說，如果 queue.yaml 上傳作業停用了現有佇列，您可以執行下列指令，透過 com.google.appengine.legacy.queue_updated 方法傳回 Disabled queue QUEUE_NAME 記錄訊息：

gcloud logging read \
  'protoPayload.methodName=
   (com.google.appengine.legacy.queue_created OR
    com.google.appengine.legacy.queue_updated OR
    google.cloud.tasks.v2.CloudTasks.CreateQueue OR
    google.cloud.tasks.v2.CloudTasks.UpdateQueue OR
    google.cloud.tasks.v2.CloudTasks.DeleteQueue)'

詳情請參閱「讀取記錄項目」。

恢復由於上傳 queue.yaml 而遭停用的佇列

如果您混用佇列管理方法，上傳 queue.yaml 檔案可能會意外停用透過 Cloud Tasks API 建立的佇列。如要恢復佇列，您可以對佇列呼叫 ResumeQueue，或將其新增到 queue.yaml 並上傳檔案。

如果您先前在 queue.yaml 設定中設定自訂處理 rate，ResumeQueue 會將佇列重設為預設的 rate。這會反映在 ResumeQueue 回應的 maxDispatchesPerSecond 欄位中。

解決配額問題

如果您使用 queue.yaml 建立佇列，專案會預設可建立的佇列數量上限配額。使用 Cloud Tasks API 建立的佇列也有預設配額。與其他情況一樣，混用 queue.yaml 和 Cloud Tasks API 方法可能會產生非預期的結果。

舉例來說，如果您使用 queue.yaml 建立佇列，之後配額增加，但您使用 Cloud Tasks API 建立其他佇列時，可能會收到配額不足的錯誤。如要解決這個問題，請使用 Google Cloud 控制台管理配額。詳情請參閱「使用控制台管理配額」。

後續步驟