使用佇列管理功能或 queue.yaml

本頁說明使用 Cloud Tasks API 管理佇列，與上傳 Cloud Tasks queue.yaml 檔案達成相同目的之間的差異。另外也會探討混用這兩種機制的一些陷阱，以及常見問題的處理方法。

簡介

Cloud Tasks API 針對 App Engine 工作佇列服務提供獨立於 App Engine 之外的介面。這個介面可讓您管理佇列，包括透過控制台或 gcloud 指令管理。透過 Cloud Tasks API 建立的佇列可透過 App Engine SDK 存取，反之亦然。為維持相容性，您可以使用 App Engine SDK 採用的設定檔 queue.yaml，建立及設定要透過 Cloud Tasks API 使用的佇列。不過，如果同時透過檔案和 Cloud Tasks API 設定，可能會產生意想不到的後果。

混合使用 queue.yaml 和 Cloud Tasks 佇列管理方法時的陷阱

對於基礎服務，queue.yaml 檔案是決定性檔案。如果上傳的 queue.yaml 省略了專案中的現有佇列，無論這些佇列是如何建立的，都會遭到「停用」或「暫停」。因此，如果您使用 Cloud Tasks API 呼叫 CreateQueue 或 UpdateQueue，然後上傳省略這些佇列的 queue.yaml 檔案，則在 Cloud Tasks 呼叫中建立的佇列會遭到停用。

請考量下列情境：

  1. 呼叫 CreateQueue 建立名為「cloud-tasks-queue」的佇列。

  2. 上傳含有下列內容的 queue.yaml 檔案：

    queue:
- name: queue-yaml-queue

這個專案中的佇列目前狀態為何？名為「cloud-tasks-queue」的佇列以及先前存在的任何其他佇列會處於 DISABLED 狀態，而名為「queue-yaml-queue」的佇列則為 RUNNING 狀態。

如果您是透過 Cloud Tasks API 建立佇列，這個行為可能會出乎您的預料。下方的操作說明提供了恢復已停用佇列的方法。

同樣地，如果佇列在 Cloud Tasks API 中遭到停用，但稍後出現在上傳的 queue.yaml 檔案中，該佇列就會恢復運作。

如果使用 DeleteQueue 方法刪除佇列，但該佇列稍後出現在 queue.yaml 檔案中，則 queue.yaml 上傳作業可能會失敗，因為刪除佇列後的幾天內，您可能無法重複使用已刪除的佇列名稱。

最佳做法

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

不過，如果您目前使用 queue.yaml，並且考慮改用佇列管理方法，請務必先瞭解混合使用 queue.yaml 與 Cloud Tasks 佇列管理方法的陷阱。

為避免使用者混用工作管理方法，您可以建立網頁應用程式或指令列工具，規定所有使用者都必須透過這些工具建立、更新及刪除佇列。該工具是使用 Cloud Tasks 佇列管理方法還是 queue.yaml，是工具的實作細節，使用者不必擔心。如果使用者必須使用該工具，即可確保 Cloud Tasks 佇列管理方法和 queue.yaml 不會意外遭到混用。為協助強制使用這類工具，您可以將佇列管理員角色授予工具，並要求使用者驗證身分才能使用工具。如要進一步瞭解存取權管理，請參閱安全佇列設定。

偵錯

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

    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 而遭到停用，稽核記錄會透過 com.google.appengine.legacy.queue_updated 方法顯示「Disabled queue '[QUEUE_NAME]'」訊息。

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

如果您混用queue.yaml和 Cloud Tasks 佇列管理方法，上傳 queue.yaml 檔案可能會意外停用透過 Cloud Tasks API 建立的佇列。

如要恢復佇列，您可以對佇列呼叫 ResumeQueue，或將其新增到 queue.yaml 並上傳檔案。請注意，如果您先前在佇列的 queue.yaml 設定中設定自訂處理 rate，ResumeQueue 會將佇列重設為預設的 rate。這會反映在 ResumeQueue 回應的 maxDispatchesPerSecond 欄位中。

配額

如果您使用 queue.yaml 建立佇列，預設最多可建立 100 個佇列。使用 Cloud Tasks API 建立的佇列，預設最多可有 1,000 個。與其他情況一樣，混用 queue.yaml 和 Cloud Tasks API 方法可能會產生非預期結果。舉例來說，假設您使用 queue.yaml 建立一些佇列，然後將配額增加到 2,000。如果您之後使用 Cloud Tasks API 方法建立更多佇列，就會發生配額錯誤。如要解決這個問題，請在 Google Cloud console 的「配額」頁面中，使用「編輯配額」提出要求。

Cloud Tasks 佇列管理方法的其他相關資訊

佇列設定與佇列啟動延遲

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

Cloud Tasks 和 default App Engine 佇列

App Engine SDK 和 Cloud Tasks API 會對名為「default」的 App Engine 佇列提供特別處置。

如果 default 佇列不存在，系統會在下列情況中建立佇列：

  1. 當初次使用 App Engine SDK 將工作新增到 default 佇列時。
  2. 上傳指定 default 佇列的 queue.yaml 檔案時。
  3. 呼叫 CreateQueue 或 UpdateQueue 來建立 default 佇列時。

為了保留與 App Engine 的相容性，Cloud Tasks 會強制執行下列限制：

  1. 如果建立了名為「default」的佇列，該佇列必須是使用 App Engine 工作的佇列。
  2. default 佇列建立後，使用者無法將其刪除。

在 Cloud Tasks API 中，default 佇列還適用下列限制：

  1. Cloud Tasks API 不會自動建立 default 佇列或任何其他佇列。
  2. 與任何其他佇列一樣，如果在佇列建立前呼叫 default 佇列上的 GetQueue，就會導致找不到錯誤。
  3. 同樣地，default 佇列不會出現在 ListQueues 的輸出內容中， 直到建立為止。
  4. default 佇列的設定可透過 UpdateQueue 呼叫變更。

後續步驟