queue.xml 參考資料

透過 App Engine SDK 管理工作佇列的應用程式會使用名為「queue.xml」的設定檔定義這些佇列。以 Java 應用程式來說,這個檔案儲存在應用程式的 WEB-INF 目錄中。您可以使用 queue.xml,同時設定發送佇列提取佇列。發送佇列含有預設佇列,因此您可以選擇是否透過這個設定檔加以設定,但提取佇列則必須在 queue.xml 中特別設定。

範例

以下的基礎範例會定義一個已命名佇列,並覆寫預設處理速率:

<queue-entries>
  <queue>
    <name>my-push-queue</name>
    <rate>1/s</rate>
  </queue>
</queue-entries>

以下是較複雜的 queue.xml 設定範例,示範如何設定工作嘗試次數及修改預設處理速率。

<queue-entries>
  <queue>
    <name>fooqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <task-retry-limit>7</task-retry-limit>
      <task-age-limit>2d</task-age-limit>
    </retry-parameters>
  </queue>
  <queue>
    <name>barqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>0</max-doublings>
    </retry-parameters>
  </queue>
  <queue>
    <name>bazqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>3</max-doublings>
    </retry-parameters>
  </queue>
</queue-entries>

語法

queue.xml 檔案是 XML 檔案,其根元素為 <queue-entries>。這個指令包含在 <queue> 元素內指定的零個或多個已命名佇列。每項佇列定義皆可指定下列元素:

元素 說明
<bucket-size> (發送佇列)

選用元素。工作佇列會使用憑證區塊演算法來控制工作執行的速率。每個已命名的佇列都有一個存放憑證的憑證區塊,其上限由 bucket_size 值指定。每次應用程式執行一項工作時,系統就會從區塊中移除一個憑證。您會繼續處理佇列中的工作,直到佇列的區塊中再也沒有憑證為止。App Engine 會依據您為佇列指定的速率,持續在區塊中補充新的憑證。

當佇列中有多個工作且處理速率相當高時,區塊大小會限制佇列的處理速度。區塊大小的最大值為 500,可使您享有高速率,讓工作在排入佇列後能立即開始處理,並且在短時間內有許多工作排入佇列時,仍可限制資源的使用量。

如果您未針對佇列指定 bucket_size,預設值為 5。建議您將此設為較大的值,因為預設大小對許多用途而言可能過小;建議大小是處理「速率」除以 5 (速率/5)。

如要進一步瞭解這項元素,請參閱 Cloud Task API 參考資料中的 max_burst_size

比較說明。
<max-concurrent-requests> (發送佇列)

選用元素。設定可透過指定佇列同步執行的工作數量上限。此元素的值為整數。根據預設,每個佇列的上限是 1000 個工作。根據預設,每個佇列的建議上限是 5000 個工作。請注意,首次建立佇列或是將佇列閒置一段時間後,佇列數量可能會慢慢增加。

限制並行工作的數量可讓您進一步控制佇列的執行速率,避免一次執行過多工作。除此之外,也可以防止資料儲存庫發生爭用狀況,讓其他佇列或線上處理作業都可使用相關資源。

如要進一步瞭解這項元素,請參閱 Cloud Tasks API 參考資料中的 max_concurrent_dispatches 比較說明。

<mode>

選用元素。識別佇列的模式。這項設定的預設值為 push,這表示佇列為發送佇列。如果您想使用提取佇列,請將模式設為 pull

<name>

必要元素。佇列的名稱。這是您在呼叫 QueueFactory.getQueue() 時指定的名稱。

佇列名稱可包含大寫和小寫字母、數字及連字號,長度上限為 100 個字元。

所有應用程式都有名稱為「default」的發送佇列。這個佇列的預設速率為每秒 5 個工作,但您可以在 queue.xml 中定義預設佇列來變更這個速率。如果您未在 queue.xml 中設定預設佇列,在您第一次使用預設佇列之前,Google Cloud Platform Console 都不會顯示預設佇列。您可以定義名為「default」的佇列,自訂這個佇列的設定。

<rate> (發送佇列)

必要元素。這個佇列處理工作的頻率。此值為後接時間單位的數字,其中單位是 s (秒)、m (分鐘)、h (小時) 或 d (天)。例如,5/m 這個值代表工作的處理速率為每分鐘 5 次。rate的最大值是 500/s

如果數字是 0 (例如 0/s),佇列會被視為「已暫停」,且不會處理任何工作。

如要進一步瞭解這項元素,請參閱 Cloud Tasks API 參考資料中的 max_dispatches_per_second 比較說明。

<retry-parameters>

選用元素。設定發送佇列中失敗工作的重試次數。新增這項元素可讓您指定在特定佇列中重試失敗工作的次數上限。您也可以設定重試工作的時間限制,以及控制每次重試的時間間隔。

重試參數可包含下列子元素:

<task-retry-limit>
重試次數。舉例來說,如果指定的數值為 0 且工作「失敗」,那麼系統完全不會「重試」工作。如果指定的數值為 1 且工作「失敗」,則系統會重試一次工作。如果未指定這項參數,系統會一直不斷重試這項工作。如果您將 task_retry_limit 指定為 task_age_limit,系統會持續重試工作,直到達到這兩項上限為止。
<task-age-limit> (發送佇列)
重試失敗工作的時間限制,從工作首次執行時開始算起。此值為後接時間單位的數字,其中單位是 s (秒)、m (分鐘)、h (小時) 或 d (天)。例如,5d 這個值指定的限制為首次嘗試執行工作後的五天。如果未指定這項參數,系統會無限期重試工作。如果您也指定了 task_retry_limit,App Engine 會持續重試工作,直到達到這兩項上限為止。
<min-backoff-seconds> (發送佇列)
工作失敗後等待重試的時間下限 (以秒為單位)。預設值為 0.1
<max-backoff-seconds> (發送佇列)
工作失敗後等待重試的時間上限 (以秒為單位)。預設值為 3600
<max-doublings> (發送佇列)
失敗工作重試間隔時間加倍遞增到常數之前,要將間隔時間加倍的次數上限。常數為:2**max_doublings * min_backoff_seconds。預設值為 16
<target> (發送佇列)

選用元素。針對執行排入此佇列的工作所用的服務/版本、前端版本或後端,指定這些服務或版本名稱的字串。預設值為空字串。

在建構工作的 HTTP 要求時,系統會在應用程式的網域名稱前面加上這個字串。例如,如果應用程式 ID 為 my-app,而且您將目標設為 my-version.my-service,網址主機名稱將設為 my-version.my-service.my-app.appspot.com

如果未指定目標,則視工作排入佇列所在的應用程式版本而定,系統會在相同的應用程式版本中叫用工作。因此,如果您將預設應用程式版本的工作排入佇列,但不指定佇列上的目標,則會在預設應用程式版本中叫用該工作。請注意,在工作排入佇列的時間與執行工作的時間之間,如果您變更預設應用程式版本,工作將會在新的預設版本中執行。

如果您將服務與分派檔案搭配使用,工作的 HTTP 要求可能會遭到攔截並重新轉送至其他服務。

您可為應用程式中的所有佇列指定下列元素 (在 <queue-entries> 根元素內設定):

元素 說明
<total-storage-limit>

選用元素。覆寫工作佇列儲存空間預設配額上限 (100M) 的字串。例如:


<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

這個配額包含在應用程式的總儲存空間配額中 (包括資料儲存庫和 Blobstore 配額)。

如未指定前置字串,系統會將您指定的數字解讀為位元組。支援的前置字串如下:

  • B (位元組)
  • K (KB)
  • M (MB)
  • G (GB)
  • T (TB)

<total-storage-limit> 會受限於應用程式的可用總磁碟儲存空間,其上限值即為可用的儲存空間量。

部署佇列設定檔

queue.xml 檔案應位於預設服務的 WEB-INF 目錄中。

如要不變更現有版本的情況下部署佇列設定檔,請使用下列指令:

appcfg.sh update_queues <application directory>

<application directory> 取代為應用程式主目錄的路徑。

刪除佇列

如要刪除佇列:

  1. queue.xml 檔案中移除佇列定義。

  2. 將變更上傳至 queue.xml 檔案。

    [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.sh update_queues [YOUR_APP_DIR]
    

    或是在 Windows 中執行下列指令:

    [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.cmd update_queues [YOUR_APP_DIR]
    
  3. 在 GCP 主控台中選取所需佇列,然後按一下 [Delete queue] (刪除佇列)

    前往「Task queues」(工作佇列) 頁面

從 GCP Consol 刪除佇列後,您必須等待 7 天,才能重新建立相同名稱的佇列。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 8 適用的 App Engine 標準環境