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

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

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

範例

以下是 cron.yaml 檔案範例：

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

語法

cron.yaml 檔案應位於應用程式的根目錄中，並與 app.yaml 搭配使用：cron.yaml 可設定 Java 8 應用程式的排程工作。

Cron 工作定義

元素 說明
description (非必要) 您可以透過 Google Cloud 主控台和開發伺服器的管理員介面查看說明。
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 服務在一天 24 小時內都會以這種間隔來執行工作，從 00:00 開始執行工作，並在每個工作完成後等待指定的持續時間，再執行下一個工作。

    範例：在 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]：整數值及對應的時間單位。有效的時間單位值：
    • minutes或mins
    • 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]：整數值及對應的時間單位。有效的時間單位值：
    • minutes或mins
    • hours
  • [INTERVAL_SCOPE]：指定與 [INTERVAL_VALUE] 對應的子句。您可以定義自訂時間範圍或使用 24 小時 synchronized 選項。
    • 加入 from [HH:MM] to [HH:MM] 子句，即可設定特定的工作開始時間，或是設定工作的執行時間範圍。

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

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

      重要事項：[INTERVAL_VALUE] 必須將 24 除成整數，否則會發生錯誤。[INTERVAL_VALUE] 的有效值包括：1、2、3、4、6、8、12 或 24。

開始時間間隔範例
以下範例可協助您瞭解如何定義使用開始時間間隔的工作排程：
  • 每天 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>

    • 若要定義特定日期，您必須使用序數。有效值是從一個月的第一天到當月的最大天數，例如：
      • 1st或first
      • 2nd 或 second
      • 3rd 或 third
      • 最多為 31st 或 thirtyfirst

      範例：

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

  • [INTERVAL_VALUE]：自訂間隔包含您要工作執行的特定日期清單。這個清單必須以逗號分隔的清單定義，且可包含下列其中一個值：
    • 該月中日期的整數值，值的上限為 31 天，例如：
      • 1
      • 2
      • 3
      • 最多為 31
    • 日期名稱可以混用下列任何完整或縮寫值：
      • monday或mon
      • tuesday 或 tue
      • wednesday 或 wed
      • thursday 或 thu
      • friday 或 fri
      • saturday 或 sat
      • sunday 或 sun
      • 使用 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]：您必須利用以逗號分隔的清單指定多個月份，可以混合使用下列完整或縮寫值：
      • january或jan
      • february 或 feb
      • march 或 mar
      • april 或 apr
      • may
      • june 或 jun
      • july 或 jul
      • august 或 aug
      • september 或 sep
      • october 或 oct
      • november 或 nov
      • december 或 dec
      • 使用 month 即可指定一年中的所有月份。
    • [HH:MM]：您必須使用 24 小時格式 HH:MM 指定時間值，其中：
      • HH 是從 00 到 23 的整數。
      • MM 是從 00 到 59 的整數。

      • 範例：

      <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

這個標頭和其他標頭是由 App Engine 在內部設定的。如果用戶端傳送這些標頭，系統會從要求中移除這些標頭。但如果要求是由舊版應用程式的登入管理員發出，由於管理員可設定標頭以進行測試，因此不會移除標頭。

來源 IP 位址

App Engine 會從 IP 位址 0.1.0.2 發出 Cron 要求。如果是使用舊版 gcloud (326.0.0 之前的版本) 建立的 Cron 工作，Cron 要求會來自 0.1.0.1。

要求逾時

Cron 要求逾時期限取決於為應用程式所設的資源調度類型：

自動調整資源配置
要求逾時時間為 10 分鐘。
基本與手動調整資源配置
要求逾時時間為 24 小時。

詳情請參閱「執行個體的管理方式」。

限制

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

開發伺服器的 Cron 支援

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

部署 Cron 工作

您可以使用 gcloud CLI 將 Cron 工作部署到 App Engine。

如要部署 cron.yaml 設定檔中指定的 Cron 工作，請執行以下指令：

gcloud

    gcloud app deploy cron.yaml

Maven

    mvn appengine:deployCron cron.yaml

Gradle

    gradle appengineDeployCron cron.yaml

IDE

如果您使用 IntelliJ 或 Eclipse，可透過部署表單選取要部署的個別設定檔。

刪除所有 Cron 工作

如要刪除所有 Cron 工作：

  1. 編輯 cron.yaml 檔案的內容，讓檔案內容如下：

    cron：

  2. 將 cron.yaml 檔案部署至 App Engine。

Google Cloud 控制台中的 Cron 支援

Google Cloud 控制台的工作佇列頁面中，有一個分頁會顯示正在執行 Cron 工作的工作。

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