以 App Engine SDK 為基礎的工具適用的 cron.xml 參考資料

使用 cron.xml 檔案定義應用程式的已排程工作。

要進一步瞭解如何排程工作,包括如何測試、部署或刪除 Cron 工作,請參閱使用 Cron 排程工作說明

範例

以下是 cron.xml 檔案範例:

<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
  <cron>
    <url>/recache</url>
    <description>Repopulate the cache every 2 minutes</description>
    <schedule>every 2 minutes</schedule>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
    <target>version-2</target>
  </cron>
</cronentries>

針對說明格式的 XSD,請檢查 SDK 中的 docs/cron.xsd 檔案。

語法

cron.xmlappengine-web.xml 檔案均應位於應用程式的 WEB-INF 目錄:cron.xml 可以設定 Java 應用程式的預定工作。

Cron 工作定義

元素 說明
<description> 選用。您可以透過 GCP 主控台和開發伺服器的管理員介面查看說明。
<retry-parameters> 選用。如果 Cron 工作要求處理常式傳回的 HTTP 狀態碼不在 200–299 (含首尾) 範圍內,則 App Engine 會將工作視為失敗。根據預設,系統不會重試失敗的工作。您可以在設定檔中加入重試參數區塊,就可以重新嘗試執行失敗的工作。

詳情請參閱重試 Cron 工作一節。

<schedule> 必要元素。定義 Cron 工作執行的排程,請參閱下方的語法
<target>

應用程式主機名稱前面會加上 target 字串,通常會是服務名稱。Cron 工作會轉送至設為接收流量的指定服務版本。

如果系統找不到針對 target 指定的服務名稱,則會將 Cron 要求轉送至 default 服務或設為接收流量的應用程式版本。如要進一步瞭解有關轉送的資訊,請參閱要求的轉送方式一文。

<timezone> timezone 應為標準的 zoneinfo 時區名稱。如果您不指定時區,工作將依世界標準時間 (亦稱為 GMT) 的時間執行。
<url> 必要元素。<url> 欄位僅為應用程式中的網址。如果 <url> 元素含有特殊 XML 字元 (例如 &<>'"),您應該將其逸出。

定義 Cron 工作 schedule

Cron 工作是按照週期性間隔安排排程,並使用簡單的類英文格式指定。您可以定義排程,讓系統一天多次執行工作,或在特定日期和月份執行。

每日多次間隔

請使用每日多次間隔,根據重複排程在一天中多次執行某個工作。您可以定義結束時間間隔或開始時間間隔:

  • 結束時間間隔:定義某個工作的「結束時間」與下一個工作的開始時間之間的間隔時間,其中「結束時間」是指工作完成的時間,或是逾時的時間。Cron 服務會從 00:00 開始,一天 24 小時都以這種間隔類型執行工作,並在每個工作完成後等待指定的持續時間,再開始下一個工作。

    範例:在 every 5 minutes 的排程中,系統每天會按照 5 分鐘的間隔來執行工作。如果根據這個排程執行的工作執行個體在 02:01 完成,則下一個工作會等待 5 分鐘,然後在 02:06 開始執行。

  • 開始時間間隔:定義 Cron 服務啟動每個工作的固定時間間隔。這與結束時間間隔不同,系統利用開始時間間隔來執行每個工作時,不會考慮到前一個工作的完成或逾時時間。您可以設定系統執行工作的時間範圍,或是讓系統從 00:00 開始,執行一天 24 小時的工作。

    由於系統會嚴格按照開始時間來執行工作,如果有某個工作執行個體的執行時間超過定義的時間間隔,Cron 服務就會略過一個工作。如果前一個工作尚未完成或逾時,系統會略過間隔中的一個開始時間。

    範例:在 every 5 minutes from 10:00 to 14:00 的排程中,系統在 10:00 執行第一個工作,然後每隔 5 分鐘就執行下一個工作。如果第一個工作執行了 7 分鐘,系統就會略過 10:05 的工作,因此,Cron 服務會等到 10:10 才執行該工作的另一個執行個體。

自訂間隔

您可以使用自訂間隔來定義排程,讓工作可以在您選取的一或數天中每天執行一次,以及在您選取的一或多個月份中每天執行一次。按照自訂排程執行的工作,只會在一整年中您所選取日期和月份的特定時間執行。

範例:在 1,2,3 of month 07:00 的排程中,工作會在每個月頭三天的 07:00 執行一次。

schedule 的重要注意事項:

  • 您必須決定要使用每日多次間隔,還是自訂間隔。請注意,您不得混用屬於不同間隔類型的元素。以下是無效時程定義的示例:<schedule>every 6 hours mon,wed,fri</schedule>
  • 無論何時,請確保您僅執行了一個工作執行個體。Cron 服務被設計成「至少會提供服務一次」;也就是說,如果您排定了工作的排程,App Engine 就至少會傳送工作要求一次。在極少數的情況下,系統可能會收到針對相同工作中多個執行個體的要求,因此您的要求處理常式必須要是冪等,且您的程式碼應該要能確保這種情況不會造成有害的副作用。

設定 schedule 的格式

若要指定工作執行的時間,您必須使用以下語法定義 schedule 元素:

<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>

選擇間隔類型以定義 schedule 元素:

結束時間間隔
  • [TYPE]:每日間隔必須包含 every 前置字串。

    範例:<schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]:整數值及對應的時間單位。有效的時間單位值:
    • minutesmins
    • hours
  • [INTERVAL_SCOPE]:不適用。如要設定特定的工作開始時間,或是設定工作的執行時間範圍,請參閱適用於開始時間間隔自訂間隔的語法。
結束時間間隔範例
以下範例可協助您瞭解如何定義使用結束時間間隔的工作排程:
  • 每天 00:00 開始執行,每項工作之間等待 5 分鐘。每項工作結束後,Cron 服務會等待 5 分鐘,再執行下一項工作:
    <schedule>every 5 minutes</schedule>
  • 每天 00:00 開始執行,每項工作之間等待 30 分鐘。每項工作結束之後,Cron 服務會等待 30 分鐘,再執行下一項工作:
    <schedule>every 30 mins</schedule>
開始時間間隔
  • [TYPE]:每日間隔必須包含 every 前置字串。

    範例:<schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]:整數值及對應的時間單位。有效的時間單位值:
    • minutesmins
    • hours
  • [INTERVAL_SCOPE] 指定與 [INTERVAL_VALUE] 對應的子句。您可以定義自訂時間範圍或使用 24 小時 synchronized 選項。
    • 使用 from [HH:MM] to [HH:MM] 子句來定義執行工作的特定開始時間和時間範圍。

      您必須使用 24 小時格式 HH:MM 指定時間值,其中:

      • HH 是從 0023 的整數。
      • MM 是從 0059 的整數。
    • 使用 synchronized 指定 24 小時時間範圍 (from 00:00 to 23:59),這個範圍按 [INTERVAL_VALUE] 值平均劃分。

      重要事項:[INTERVAL_VALUE] 必須將 24 除成整數,否則會發生錯誤。[INTERVAL_VALUE] 的有效值包括:1234681224

開始時間間隔範例
以下範例可協助您瞭解如何定義使用開始時間間隔的工作排程:
  • 每天 10:00 到 14:00 期間內每隔 5 分鐘執行:
    <schedule>every 5 minutes from 10:00 to 14:00</schedule>
  • 每天 08:00 到 16:00 期間內每小時執行一次:
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • 每天從 00:00 開始每隔兩小時執行一次:
    <schedule>every 2 hours synchronized</schedule>
自訂間隔
  • [TYPE]:自訂間隔可以含有 every 前置字串用來定義重複間隔,或者您可以定義一個月中特定的日期清單:
    • 若要定義重複間隔,您可以使用 every 前置字串。

      範例:

      <schedule>every day 00:00</schedule>
      <schedule>every monday 09:00</schedule>

    • 若要定義特定日期,您必須使用序數。有效值是從一個月的第一天到當月的最大天數,例如:
      • 1stfirst
      • 2ndsecond
      • 3rdthird
      • 最多到 31stthirtyfirst

      範例:

      <schedule>1st,3rd tuesday</schedule>
      <schedule>2nd,third wednesday of month 09:00</schedule>

  • [INTERVAL_VALUE]:自訂間隔包含您要工作執行的特定日期清單。這個清單必須以逗號分隔的清單定義,且可包含下列其中一個值:
    • 該月中日期的整數值,值的上限為 31 天,例如:
      • 1
      • 2
      • 3
      • 最多為 31
    • 日期名稱可以混合使用下列任何完整或縮寫值:
      • mondaymon
      • tuesdaytue
      • wednesdaywed
      • thursdaythu
      • fridayfri
      • saturdaysat
      • sundaysun
      • 使用 day 指定一週的所有日子。

    範例:

    <schedule>2nd monday,thu</schedule>
    <schedule>1,8,15,22 of month 09:00</schedule>
    <schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [INTERVAL_SCOPE] 指定與 [INTERVAL_VALUE] 對應的子句。自訂間隔可以包含指定一年中單一月份的 of [MONTH] 子句,或是以逗號分隔的多個月份清單。您也必須定義想要工作執行的特定時間,例如:of [MONTH] [HH:MM]

    根據預設,如果排除了 of 子句,則自訂間隔為每個月執行。

    • [MONTH]:您必須以逗號分隔的清單指定多個月份,可以混合使用下列完整或縮寫值:
      • januaryjan
      • februaryfeb
      • marchmar
      • aprilapr
      • may
      • junejun
      • julyjul
      • augustaug
      • septembersep
      • octoberoct
      • novembernov
      • decemberdec
      • 使用 month 指定一年中的所有月份。
    • [HH:MM]:您必須使用 24 小時格式 HH:MM 指定時間值,其中:
      • HH 是從 0023 的整數。
      • MM 是從 0059 的整數。
    • 範例:

      <schedule>1st monday of sep,oct,nov 09:00</schedule>
      <schedule>1 of jan,april,july,oct 00:00</schedule>

自訂間隔範例
以下範例可協助您瞭解如何定義使用自訂間隔的工作排程:
  • 每天 00:00 執行:
    <schedule>every day 00:00</schedule>
  • 每星期一 09:00 執行:
    <schedule>every monday 09:00</schedule>
  • 三月第二個星期三的 17:00 執行一次:
    <schedule>2nd wednesday of march 17:00</schedule>
  • 五月執行六次。在首兩週的每個星期一、星期三和星期五的 10:00 執行一次。
    <schedule>1st,second mon,wed,fri of may 10:00</schedule>
  • 每週執行一次。從每個月第一天開始,每隔七天在 09:00 執行一次:
    <schedule>1,8,15,22 of month 09:00</schedule>
  • 每隔一週執行一次。在每個月的第一個和第三個星期一的 04:00 執行一次:
    <schedule>1st,third monday of month 04:00</schedule>
  • 每年執行三次。在九月、十月和十一月的第一個星期一的 09:00 執行一次:
    <schedule>1st monday of sep,oct,nov 09:00</schedule>
  • 每一季執行一次。在一月、四月、七月和十月的第一天的 00:00 執行一次:
    <schedule>1 of jan,april,july,oct 00:00</schedule>

重試 Cron 工作

如果 Cron 工作要求處理常式傳回的 HTTP 狀態碼不在 200–299 (含首尾) 範圍內,則 App Engine 會將工作視為失敗。根據預設,系統不會重試失敗的工作。只要在設定檔中加入 <retry-parameters> 區塊,即可重新執行失敗的工作。

下列 cron.xml 檔案範例中包含一項 Cron 工作,這項工作已設為最多重試五次 (預設值),初始輪詢時間為 2.5 秒,每次重試後即會加倍。

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

Cron 重試語法

下表將進一步說明重試參數。

元素 說明
<job-retry-limit> 失敗 Cron 工作的重試次數上限不得超過 5 次。如果您也指定了 <job-age-limit>,App Engine 會重試 Cron 工作,直到達到這兩個上限為止。如果您未在參數中設定這項元素,系統會依預設將上限設為 5 次。
<job-age-limit> 重試 Cron 失敗工作的時間限制,從 Cron 工作首次執行起算。此值為後接時間單位的數字,其中單位是 s (秒)、m (分鐘)、h (小時) 或 d (天)。舉例來說,5d 這個值指定的限制為系統首次嘗試執行 Cron 工作後的五天內。如果您也指定了 <job-retry-limit>,App Engine 會重試 Cron 工作,直到達到這兩個上限為止。
<min-backoff-seconds> Cron 工作失敗後等待重試的時間下限 (以秒為單位)。
<max-backoff-seconds> Cron 工作失敗後等待重試的秒數上限。
<max-doublings> Cron 失敗工作重試間隔時間加倍遞增到常數之前,要將此間隔加倍的次數上限。常數為:2**(max_doublings - 1) * min_backoff

Cron 要求

要求標頭

Cron 服務的要求會包含 HTTP 標頭:

X-Appengine-Cron: true

X-Appengine-Cron 標頭是由 Google App Engine 在內部設定的。如果要求處理常式發現這個標頭,即可信任這個要求為 Cron 要求。如果標頭出現在應用程式的外部使用者要求中,則會遭到移除。然而,如果要求是由已登入應用程式的管理員發出,由於管理員可設定標頭以進行測試,因此不會移除標頭。

來源 IP 位址

Google App Engine 會從 IP 位址 0.1.0.1 發出 Cron 要求。

期限

Cron 逾時期限取決於針對應用程式所設的執行個體類別和資源調度類型:

自動彈性調整資源配置
逾時時間為大約 10 分鐘。
基本與手動調整資源配置
逾時時間最長可達 24 小時。

詳情請參閱資源調度類型和執行個體類別一文

限制

免費的應用程式最多可以排定 20 項工作,付費應用程式則最多可以排定 250 項工作。

開發伺服器的 Cron 支援

開發伺服器不會自動執行您的 Cron 工作。您可以使用 curl 或類似的工具,以本機 Cron 或排定排程的工作介面觸發工作網址。

部署 Cron 工作

您可以使用 appcfg.sh 工具將 Cron 工作部署至 App Engine。

選項 1:上傳整個應用程式

如要上傳整個應用程式,並使用 cron.xml 檔案中的項目更新 Cron 服務,請執行以下指令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
選項 2:僅上傳您的 Cron 更新內容

如要僅更新 Cron 設定而不上傳應用程式的其餘部分,請執行以下指令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

刪除所有 Cron 工作

如要刪除所有 Cron 工作,請按照下列指示操作:

  1. 按照下列方式修改 cron.xml 檔案中的內容:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    
  2. cron.xml 檔案部署至 App Engine。

GCP 主控台中的 Cron 支援

GCP 主控台的工作佇列頁面中,有一個分頁會顯示正在執行 Cron 工作的工作。

您也可以前往「Logs」(記錄檔) 頁面,查看先前新增或移除 Cron 工作的時間。

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

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

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