使用 cron.yaml 排定工作

您可以透過 App Engine Cron 服務來設定經常性的排程工作，依照您定義的時間或頻率來執行特定的作業。這類工作通常稱為「Cron 工作」，是由 App Engine Cron Service 自動觸發。舉例來說，您可以使用這個服務每天寄送一次電子郵件報告、每 10 分鐘更新一次快取資料，或每小時更新一次摘要資訊。

Cron 工作會在已設定 Cron 工作所在的應用程式中，對指定端點發出排程 HTTP GET 要求。該端點的處理常式會在收到呼叫時執行邏輯。

App Engine Cron 服務無法用於呼叫 App Engine 主機應用程式以外的網頁端點。此外，也無法用於呼叫主機應用程式以外的其他應用程式 App Engine 端點。

Cron 工作要求必須遵循與其他 HTTP 要求相同的限制。免費的應用程式最多可以排定 20 項工作，付費應用程式則最多可以排定 250 項工作。

如要部署或更新排程，您的帳戶需要下列其中一種 身分與存取權管理 角色：

您可以在 Google Cloud 控制台的「IAM」頁面中設定權限。

關於 cron 設定檔

對於 Java 以外的所有執行階段，應用程式根目錄中的 cron.yaml 檔案 (與 app.yaml 並排) 可設定應用程式的排定工作。

針對 Java，應用程式 WEB-INF 目錄中的 cron.yaml 檔案 (與 apppengine-web.xml 並排) 可設定應用程式的排定工作。

以下是 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 檔案採用 YAML 語法，且包含各個 Cron 工作的定義。工作定義必須具備 url 和 schedule。但您也可以視需要指定 description、timezone、target 和 retry_parameters：

url
必填。應用程式中的網址，為 Cron 服務在傳送工作要求時的目標網址。
schedule
必填。定義工作的執行排程，請參閱下列語法。
description
選用。Cron 工作的說明，可在 Google Cloud 主控台查看。
timezone
選用。工作排程所使用的時區名稱或「zoneinfo」。如果您沒有指定時區，排程會採用 UTC (亦稱為 GMT) 時區。
target
選用。應用程式中特定服務的名稱。如果您已指定 target，Cron 服務就會將工作要求的目標設至應用程式中的該項服務。系統會把工作要求轉送至特定服務中已設為接收流量的版本。 瞭解要求的轉送方式。

target 相關重要事項：

  • 如果您已啟用 流量拆分功能，系統就不會根據您設定的不同版本來拆分工作要求：
    • IP 位址拆分功能：來自 Cron 服務的工作要求一律都是從相同的 IP 位址傳送，因此每次都會轉送至相同的版本。
    • Cookie 拆分功能：工作要求不包括含有要求的 Cookie，因此不會轉送至任何其他版本。
  • 如果您使用分派檔案，也在 dispatch.yaml 中設定了相同的網址，系統可能會重新轉送您的工作。舉例來說，如果您同時在下列 cron.yaml 和 dispatch.yaml 檔案中定義 /tasks/hello_service2 網址，即使您已指定 target: service1，系統仍會將工作要求傳送至 service2：

    cron.yaml: 

    cron:
- description: "test dispatch vs target"
  url: /tasks/hello_service2
  schedule: every 1 mins
  target: service1

    dispatch.yaml：

    dispatch:
- url: '*/tasks/hello_service2'
  service: service2
retry_parameters
選用。指定要重新執行失敗的工作，請參閱下方語法。

定義 Cron 工作 schedule

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

每日多次間隔

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

  • 結束時間間隔：定義工作「結束時間」到下一個工作開始時間的間隔時間，其中「結束時間」是指工作完成時間或逾時時間。Cron 服務在一天 24 小時內都會以這種間隔來執行工作，從工作建立/更新時間後的一個間隔開始，並在每個工作完成後等待指定的間隔，再執行下一個工作。

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

  • 開始時間間隔：定義 Cron 服務啟動每個工作的固定時間間隔。這與結束時間間隔不同，系統利用開始時間間隔來執行每個工作時，不會考慮到前一個工作完成或逾時的時間。您可以設定系統執行工作的時間範圍，或是讓系統從指定時間範圍的開始時間起，執行一天 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。
  • 不論何時，系統都只能執行一個工作例項。Cron 服務旨在提供「至少一次」傳遞；亦即，如果工作已排程，則 App Engine 至少會傳送一次工作要求。在極少數情況下，系統可能會收到針對相同工作的多次請求，因此您的要求處理常式必須是冪等，且您的程式碼應確保這種情況不會造成有害的副作用。

設定 schedule 的格式

如要指定工作執行的時間，您必須使用下列語法定義 schedule 元素：

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

然後選擇間隔類型來定義 schedule 元素：

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

    範例：schedule: every 12 hours

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

    範例：schedule: every 12 hours

  • [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
  • 每天 08:00 到 16:00 期間內每小時執行一次：
    schedule: every 1 hours from 08:00 to 16:00
  • 每天從 00:00 開始每隔兩小時執行一次：
    schedule: every 2 hours synchronized
自訂間隔
  • [TYPE]：自訂間隔可含有 every 前置字串用來定義重複間隔，或者您可以定義一個月中特定的日期清單：
    • 如要定義重複間隔，您可以使用 every 前置字串。

      範例：

      schedule: every day 00:00
schedule: every monday 09:00

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

      範例：

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

  • [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: 1,8,15,22 of month 09:00
schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [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: 1 of jan,april,july,oct 00:00

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

指定重試的次數與時間

如果 Cron 工作的要求處理常式傳回的狀態碼不在 200 至 299 (含首尾) 範圍內，App Engine 會認定該項工作失敗。根據預設，系統不會重試失敗的工作。只要在設定檔中加入 retry_parameters 區塊，就可以重新嘗試執行失敗的工作。

下列 cron.yaml 檔案範例包含一項 Cron 工作，這項工作的設定是最多重試五次，且起始輪詢時間是 2.5 秒，之後每次都會加倍。

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    job_retry_limit: 5
    min_backoff_seconds: 2.5
    max_doublings: 5

Cron 重試語法

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

元素 說明
job_retry_limit 整數，代表失敗 Cron 工作重試次數上限。最小值為 0，最大值為 5。如果您也指定了 job_age_limit，App Engine 會重試 Cron 工作，直到達到這兩個上限為止。job_retry_limit 的預設值為 0。
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 網址的要求是否來自 App Engine，而不是其他來源。您可以驗證該要求的 HTTP 標頭和來源 IP 位址來達到此目的：

  • Cron 服務的要求會包含下列 HTTP 標頭：

    "X-Appengine-Cron": "true"

    這個標頭和其他標頭是由 App Engine 在內部設定的。如果用戶端傳送這些標頭，系統會從要求中移除這些標頭。

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

針對 Java 執行階段，您可以在 Jetty 或 Tomcat 中透過篩選器執行此驗證。

要求逾時

Cron 要求的逾時時間為 60 分鐘。

如要進一步瞭解各環境和調整類型的要求逾時，請參閱「選擇 App Engine 環境」。

上傳 Cron 工作

如要上傳 Cron 工作，您必須在以下 gcloud 指令中將 cron.yaml 指定為參數：

gcloud app deploy cron.yaml

刪除 Cron 工作

如要刪除所有的 Cron 工作，請變更 cron.yaml 檔案，讓檔案僅包含：

cron:

Google Cloud 控制台中的 Cron 支援

您可以在 Google Cloud 主控台的「Cron jobs」(Cron 工作) 頁面，查看已加入排程的 Cron 工作。

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