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 可設定 PHP 5 應用程式的預定工作。

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

Cron 工作定義

元素 說明
description 選用。您可以透過 GCP Console 和開發伺服器的管理員介面查看說明。說明值的前後必須加上引號。
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 服務在一天中的 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
  • 每年執行三次。在 9 月、10 月和 11 月第一個星期一的 09:00 執行一次:
    schedule: 1st monday of sep,oct,nov 09:00
  • 每一季執行一次。在 1 月、4 月、7 月和 10 月第一天的 00:00 執行一次:
    schedule: 1 of jan,april,july,oct 00:00

重試 Cron 工作

如果 Cron 工作要求處理常式傳回的 HTTP 狀態碼不在 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 服務的要求中會包含 HTTP 標頭:

X-Appengine-Cron: true

Google App Engine 會在內部設定 X-Appengine-Cron 標頭。要求處理常式找到這個標頭之後,即可確認這項要求屬於 Cron 要求。如果外部使用者對應用程式發出的要求中包含這個標頭,系統會移除這個標頭。不過,如果要求是由已登入帳戶的應用程式管理員發出,由於管理員可以設定標頭來進行測試,系統並不會移除標頭。

來源 IP 位址

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

期限

Cron 逾時期限取決於應用程式的執行個體類別和資源調度類型設定值:

自動調整資源配置
逾時時間約為 10 分鐘。
基本與手動資源調度
逾時時間最長可達 24 小時。

詳情請參閱資源調度類型和執行個體類別的相關說明

限制

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

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

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

這個網頁
PHP 5 適用的 App Engine 標準環境