cron.yaml 參考資料

使用 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 可設定 Python 2 應用程式的排程工作。

如要進一步瞭解 YAML 格式,請參閱 YAML 網站

Cron 工作定義

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

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

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

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

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

如果您使用分派檔案,則系統可能會重新轉送您的工作。舉例來說,如果指定了 cron.yamldispatch.yaml 檔案,即使工作的目標是 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
timezone timezone 應為標準的 zoneinfo 時區名稱。如果您不指定時區,排程將依 UTC (亦稱為 GMT) 的時間排定。
url 必要元素。url 欄位指定應用程式中由 Cron 服務叫用的網址。詳情請參閱設定 Cron 網址安全性一節。

定義 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
  • 不論何時,系統都只能執行工作的一個執行個體。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 工作

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

下列範例 cron.xml 檔案包含一項 Cron 工作,這項工作的設定是最多重試五次 (預設值),開始輪詢時間是 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 服務的要求會包含 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 項工作。

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

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

這個網頁
Python 2 適用的 App Engine 標準環境