以 Cloud SDK 為基礎的工具適用的 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 檔案可以位於原始碼中的任何位置。cron.yaml 可設定 Java 應用程式的排程工作。

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

Cron 工作定義

元素	說明
`description`	選用元素。GCP 主控台和開發伺服器的管理員介面皆可查看說明。說明值的前後必須加上引號。
`retry_parameters`	選用元素。如果 Cron 工作要求處理常式傳回的 HTTP 狀態碼不在 200–299 (含首尾) 範圍內，則 App Engine 會將工作視為失敗。根據預設，系統不會重試失敗的工作。您可以在設定檔中加入重試參數區塊，就可以重新嘗試執行失敗的工作。詳情請參閱重試 Cron 工作一節。
`schedule`	必要元素。定義 Cron 工作執行的排程，請參閱下方的語法。
`target`	應用程式主機名稱前面會加上 `target` 字串，通常會是服務名稱。Cron 工作會轉送至設為接收流量的指定服務版本。警告︰如果您在已啟用流量拆分功能的狀態下執行 Cron 工作，請多加留意。Cron 工作要求一律會從相同的 IP 位址發出，因此如果您透過 IP 位址拆分流量，則邏輯每次都會將要求轉送至相同的版本。如果您透過 Cookie 拆分流量，則系統完全不會區分要求，因為要求中不包含任何 Cookie。如果系統找不到針對 `target` 指定的服務名稱，則會將 Cron 要求轉送至 `default` 服務或設為接收流量的應用程式版本。如要進一步瞭解有關轉送的資訊，請參閱要求的轉送方式。如果您使用分派檔案，則系統可能會重新轉送您的工作。舉例來說，如果指定了 `cron.yaml` 和 `dispatch.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]：整數值及對應的時間單位。有效的時間單位值：
- minutes 或 mins
- 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]：整數值及對應的時間單位。有效的時間單位值：
- minutes 或 mins
- hours
[INTERVAL_SCOPE] 指定與 [INTERVAL_VALUE] 對應的子句。您可以定義自訂時間範圍或使用 24 小時 synchronized 選項。
- 使用 from [HH:MM] to [HH:MM] 子句來定義執行工作的特定開始時間和時間範圍。
  您必須使用 24 小時格式 HH:MM 指定時間值，其中：
  - HH 是從 00 到 23 的整數。
  - MM 是從 00 到 59 的整數。
- 使用 synchronized 指定 24 小時時間範圍 (from 00:00 to 23:59)，這個範圍按 [INTERVAL_VALUE] 值平均劃分。
  重要事項：[INTERVAL_VALUE] 必須將 24 除成整數，否則會發生錯誤。[INTERVAL_VALUE] 的有效值包括：1、2、3、4、6、8、12 或 24。

開始時間間隔範例

以下範例可協助您瞭解如何定義使用開始時間間隔的工作排程：

每天 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
```
- 若要定義特定日期，您必須使用序數。有效值是從一個月的第一天到當月的最大天數，例如：
  - 1st 或 first
  - 2nd 或 second
  - 3rd 或 third
  - 最多到 31st 或 thirtyfirst
  範例：
```
schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00
```
[INTERVAL_VALUE]：自訂間隔包含您要工作執行的特定日期清單。這個清單必須以逗號分隔的清單定義，且可包含下列其中一個值：
- 該月中日期的整數值，值的上限為 31 天，例如：
  - 1
  - 2
  - 3
  - 最多為 31
- 日期名稱可以混合使用下列任何完整或縮寫值：
  - monday 或 mon
  - tuesday 或 tue
  - wednesday 或 wed
  - thursday 或 thu
  - friday 或 fri
  - saturday 或 sat
  - sunday 或 sun
  - 使用 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]：您必須以逗號分隔的清單指定多個月份，可以混合使用下列完整或縮寫值：
  - january 或 jan
  - february 或 feb
  - march 或 mar
  - april 或 apr
  - may
  - june 或 jun
  - july 或 jul
  - august 或 aug
  - september 或 sep
  - october 或 oct
  - november 或 nov
  - december 或 dec
  - 使用 month 指定一年中的所有月份。
- [HH:MM]：您必須使用 24 小時格式 HH:MM 指定時間值，其中：
  - HH 是從 00 到 23 的整數。
  - MM 是從 00 到 59 的整數。

自訂間隔範例

以下範例可協助您瞭解如何定義使用自訂間隔的工作排程：

每天 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 項工作。

開發伺服器的 Cron 支援

開發伺服器不會自動執行您的 Cron 工作。您可以使用 curl 或類似的工具，以本機 Cron 或排定排程的工作介面觸發工作網址。

部署 Cron 工作

您可以使用 gcloud 工具，將 Cron 工作部署到 App Engine。您也可以利用 Maven 或 Gradle App Engine 外掛程式，或是透過 IntelliJ 或 Eclipse 進行部署。


若要部署 cron.yaml 設定檔中指定的 Cron 工作，請執行以下指令： gcloud gcloud app deploy cron.yaml Maven mvn appengine:deployCron cron.yaml Gradle gradle appengineDeployCron cron.yaml IDE 如果您使用 IntelliJ 或 Eclipse，可透過部署表單選取要部署的個別設定檔。

刪除所有 Cron 工作

如要刪除所有 Cron 工作：

將 cron.yaml 檔案的內容改為：
```
cron:
```
將 cron.yaml 檔案部署至 App Engine。

GCP 主控台中的 Cron 支援

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

您也可以前往「Logs」(記錄檔) 頁面，查看先前新增或移除 Cron 工作的時間。

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新：十二月 5, 2019。