使用 cron.yaml 排定工作

透過 App Engine Cron 服務,您可以定期設定排程工作;這些排程工作會依照您定義的次數或時間間隔來執行,。這類 Cron 工作是由 App Engine Cron Service 自動觸發。舉例來說,您可以使用此服務每天寄送電子郵件報告、每 10 分鐘更新快取資料,或每小時更新摘要資訊。

Cron 工作會在每天的指定時間使用 HTTP GET 要求叫用網址,Cron 叫用的 HTTP 要求最多可執行 60 分鐘,但必須遵循與其他 HTTP 要求相同的限制

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

關於 cron 設定檔

應用程式根目錄中的 cron.yaml 檔案可 (隨 app.yaml 一起) 設定 .NET 應用程式的排定工作。以下是 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 工作的定義。工作定義必須具備 urlschedule,但您也可以視需要指定 descriptiontimezonetargetretry_parameters

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

target 的重要注意事項:

  • 如果您已啟用流量拆分功能,系統就不會根據您設定的不同版本來拆分工作要求:
    • IP 位址拆分功能:來自 Cron 服務的工作要求一定都是從相同的 IP 位址傳送出來的,因此系統每次都會把這些要求轉送至相同的版本。
    • Cookie 拆分功能:工作要求不會包括有 Cookie 的要求,因此系統不會把這些要求轉送至任何其他的版本。
  • 如果您使用分派檔案,也在 dispatch.yaml 中設定了相同的網址,系統就可能會重新轉送您的工作。舉例來說,如果您同時在下列 /tasks/hello_service2cron.yaml 檔案中定義 dispatch.yaml 網址,即使您指定了 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 小時內都會以這種間隔來執行工作,從 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
  • 您應該要讓系統在同一時間只執行一個工作執行個體。Cron 服務被設計成「至少會提供服務一次」;也就是說,如果您排定了工作的排程,App Engine 就至少會傳送工作要求一次。在極少數的情況下,系統可能會收到針對相同工作中多個執行個體的要求,因此您的要求處理常式必須要是冪等,且您的程式碼應該要能確保這種情況不會造成有害的副作用。

設定 schedule 的格式

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

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

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

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

    範例:schedule: every 12 hours

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

    範例:schedule: every 12 hours

  • [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
  • 每天 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

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

      範例:

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

  • [INTERVAL_VALUE]:自訂間隔包含您要工作執行的特定日期清單。這個清單必須以逗號分隔的清單定義,且可包含下列其中一個值:
    • 該月中日期的整數值,值的上限為 31 天,例如:
      • 1
      • 2
      • 3
      • 最多為 31
    • 日期名稱可以混合使用下列任何完整或縮寫值:
      • mondaymon
      • tuesdaytue
      • wednesdaywed
      • thursdaythu
      • fridayfri
      • saturdaysat
      • sundaysun
      • 使用 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]:您必須以逗號分隔的清單指定多個月份,可以混合使用下列完整或縮寫值:
      • 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: 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.xml 檔案包含一個 Cron 工作,這項工作的設定是最多重試 5 次 (預設值),且起始輪詢時間是 2.5 秒,之後每次都會加倍。

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

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 網址的要求是否來自 App Engine,而不是其他來源。您可以驗證該要求的 HTTP 標頭和來源 IP 位址來達到此目的:

  • 來自 Cron 服務的要求也會包含 HTTP 標頭:

    X-Appengine-Cron: true
    

    X-Appengine-Cron 標頭由 Google App Engine 於內部設定。如果您的要求處理常式發現這個標頭,即可信任這個要求為 Cron 要求。如果 X- 標頭來自外部來源,App Engine 就會將其移除,因此您可以信任此標頭。

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

上傳 Cron 工作

如要上傳 Cron 工作,您必須指定 cron.yaml 當做下列 gcloud 指令的參數:

gcloud beta app deploy cron.yaml

刪除 Cron 工作

如要刪除所有 Cron 工作,請變更 cron.yaml 檔案,讓檔案僅包含以下內容:

cron:

顯示工作資訊

您可以使用 appcfg.py cron_info 指令來顯示 Cron 工作的剖析版本,包括工作將要執行的時間。

請注意,如果您指定世界標準時間以外的時區,則 appcfg.py cron_info 將無法正確運算時間表。

Google Cloud Platform 主控台中的 Cron 支援

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

您也可以造訪記錄頁面,查看新增或移除 Cron 工作的時間。

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

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

這個網頁
.NET 文件適用的 App Engine 彈性環境