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 應用程式的排定工作。

如要進一步瞭解 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 檔案,則工作將會在 service2 中執行 (即使該工作的目標是 service1):


# 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 服務會一天 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
      • tuesdaytues
      • wednesdaywed
      • thursdaythurs
      • fridayfri
      • saturdaysat
      • sundaysun
      • 使用 day 指定一週的所有日子。

    範例:

    schedule: 2nd monday,thurs
    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 工作的要求處理常式傳回的狀態碼不在 200–299 (含首尾) 範圍內,App Engine 會將工作視為失敗。根據預設,系統不會重試失敗的工作。您可在設定檔中加入 retry_parameters 參數區塊,以重試執行失敗的工作。

下列 cron.yaml 範例檔案包含一項 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 項工作。

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

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

這個網頁
App Engine standard environment for Python 2