使用 cron.yaml 排定工作

您可以透過 App Engine Cron 服務安排依定義的次數或規律間隔定期運作的工作。這類工作一般稱為「Cron 工作」。App Engine Cron 服務會自動觸發 Cron 工作。舉例來說,您可以使用此服務每天透過電子郵件寄送報告、每 10 分鐘更新快取資料,或是每小時更新摘要資訊。

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

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

關於 cron 設定檔

應用程式根目錄中的 cron.yaml 檔案 (與 app.yaml 在目錄中並排) 可設定 Node.js 應用程式的排定工作。以下是 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 中也設定相同網址時,系統可能會重新轉送您的工作。舉例來說,如果同時在下列的 cron.yamldispatch.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 小時 (從 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 工作的要求處理常式傳回的狀態碼不在 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 網址的要求是來自 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 app deploy cron.yaml

刪除 Cron 工作

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

cron:

顯示工作資訊

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

提醒您,如果您指定 UTC 以外的時區,appcfg.py cron_info 將無法正確運算時間表。

Google Cloud Platform 主控台中的 Cron 支援

在 GCP 主控台的工作佇列頁面中,有一個分頁會顯示正在執行 Cron 工作的工作。

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

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

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

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