Cron 工作格式和時區

Cron 工作會定期執行,排程格式以 unix-cron 為基礎。您可以定義排程,讓系統一天多次執行工作,或是僅在特定日期和月份執行。(雖然我們不再建議使用,但仍支援建立 cron.yaml 檔案來排定現有工作)。

Cloud Scheduler 也支援使用更易於人類閱讀的格式排定工作。詳情請參閱本文「替代工作格式」一節。

Cron 工作格式

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Cloud Scheduler REST API 設定排程。

排程是以 unix-cron 字串格式 (* * * * *) 定義,這是一行五個欄位的組合,指出應執行工作的時間。

時間欄位具有下列格式和可能的值,且必須遵循以下順序:

|------------------------------- Minute (0-59)
|     |------------------------- Hour (0-23)
|     |     |------------------- Day of the month (1-31)
|     |     |     |------------- Month (1-12; or JAN to DEC)
|     |     |     |     |------- Day of the week (0-6; or SUN to SAT; or 7 for Sunday)
|     |     |     |     |
|     |     |     |     |
*     *     *     *     *
欄位 有效值的格式
分鐘 0-59
小時 0-23
日 1-31
月 1 至 12 (或 JAN 至 DEC)
星期幾 0 至 6 (或 SUN 至 SAT,或 7 代表星期日)
  • 分鐘:表示工作在整點過後多久執行,以分鐘為單位。舉例來說,如果將分鐘設為 0,工作就會在整點執行 (因為整點是 0 分鐘)。如果小時是上午 8:00,工作就會在上午 8:00 執行。

  • 小時:表示工作在午夜過後多久執行,以小時為單位 (無條件捨去至最接近的小時,因為剩餘的分鐘數會顯示在 minute 欄位中)。午夜為 0,中午為 12。舉例來說,如果小時設為 0,工作就會在午夜執行 (因為這是午夜後 0 小時)。

  • Day of the month:表示當月的日曆日期。例如,1 代表當月第一天。Cloud Scheduler 不支援以 L 表示當月最後一天。

  • Month:表示月份。請指定月份數字,或月份名稱的前三個字母 (大寫)。例如,1 代表 1 月,或等同於 JAN。

  • Day of the week:表示星期幾。例如,星期一是 1,星期二是 2。0或 7皆可代表星期日。請以數字或星期名稱的前三個大寫字母指定星期幾 (例如 SUN 代表星期日)。

    • 除非其中一個欄位標示為星號 (*) 的不受限制,否則這個欄位會與 day of the month 欄位一起評估為包含 OR。舉例來說,如果日期設為 1,星期設為 SAT,則工作會在每月的第一天和每月的每個星期六執行,即使每月的第一天不是星期六也一樣。如果星期幾不受限制 (設為 *),工作只會在每月的第一天執行。

符合所有值

如要比對欄位的所有值,請使用星號:*。如果欄位設為星號,只要其他欄位條件符合,該欄位就會與該欄位的所有有效值相符。將欄位設為星號有時稱為將欄位設為「不受限制」,因為欄位不受限於特定值。

以下是兩個未限制分鐘欄位的範例:

  • * 0 1 1 1:工作會在 1 月 1 日和星期一的午夜時段每分鐘執行一次。
  • * * * * *:工作每分鐘執行一次 (每小時、每個月的每一天、每個月、每週的每一天,因為這些欄位也都不受限制)。

星號相當於範圍的特殊案例,範圍從欄位的第一個有效值開始,到欄位的最後一個有效值結束 (例如分鐘欄位的 0-59)。

比對範圍

如要比對某個範圍的值,請指定起始值和結束值,並以連字號 (-) 分隔。範圍中不得包含空格。範圍包含邊界值。第一個數字必須小於第二個數字。如果使用月份或星期幾的縮寫名稱 (例如,使用 JAN 而非 1 代表一年的第一個月),則第一個值在月份或星期中的順序必須早於第二個值。

下列等效範例會在週一、週二、週三、週四和週五的午夜執行 (所有月份):

  • 0 0 * * 1-5
  • 0 0 * * MON-FRI

比對清單

清單可包含欄位的任何有效值,包括範圍。指定值,並以半形逗號 (,) 分隔。清單中請勿包含空格。

範例:

  • 0 0,12 * * *:工作會在午夜和中午執行。
  • 0-5,30-35 * * * *:工作會在每半小時的前五分鐘執行 (整點和半點)。

略過範圍內的值

您可以指定範圍內的步進率,略過範圍內的值。這有時稱為使用「階梯函數」(或階梯「值」或「費率運算式」)。方法是指定範圍,後面加上正斜線 (/) 和略過範圍的頻率。

您可以使用星號 (*) 表示欄位的所有值範圍。使用星號時,範圍中的第一個值為:分鐘、小時和星期幾 (星期日) 欄位為 0,日期和月份欄位為 1。

步進值不得大於欄位的最大可能值。 預設步長為 1,因此步長函式 /1 與完全不使用步長函式相同。

使用階梯函數的範圍範例:

  • */2:這是任何欄位的有效階梯函數。在分鐘欄位中,這會比對 0、2、4、...、58。小時則會比對 0、2、4、...、22。如果是當月日期,則會比對 1、3、5、...、31 (如果當月有 31 天)。月份則符合 1、3、5、...、11。星期幾則符合 0、2、4、6。

  • 0-12/2:這是分鐘和小時欄位的有效步進函式。比對結果為 0、2、4、...、12。

使用階梯函式的排程範例:

  • */2 * * * *:工作每兩分鐘執行一次。

  • 0 0-12/2 * * *:工作每兩小時執行一次,在整點執行。第一次執行時間為午夜。最後一班車是中午。

時間表範例

下表列出一些 Cron 工作排程範例和說明:

排程 Cron 工作格式 說明
每分鐘 * * * * * 每分鐘執行一次。例如上午 9:00、上午 9:01、上午 9:02 等。
每小時 0 * * * * 每小時執行一次。例如上午 9:00、上午 10:00、上午 11:00 等。
每天 0 0 * * * 每天凌晨 12:00 (24 小時制的 00:00) 執行。
平日
(週一至週五)
以下兩者等效:
  • 0 0 * * 1-5
  • 0 0 * * MON-FRI
在週一、週二、週三、週四和週五的 12:00 AM (24 小時制的 00:00) 執行。
每週 以下兩者等效:
  • 0 0 * * 0
  • 0 0 * * 7
  • 0 0 * * SUN
在週日凌晨 12:00 (24 小時制為 00:00) 執行。
每個月 0 0 1 * * 在每月第一天的凌晨 12:00 (24 小時制的 00:00) 執行。
每季 以下兩者等效:
  • 0 0 1 1,4,7,10 *
  • 0 0 1 JAN,APR,JUL,OCT *
在每季第一天的凌晨 12:00 (24 小時制的 00:00) 執行,標準季度排程為 1 月 1 日、4 月 1 日、7 月 1 日和 10 月 1 日。
每年 以下兩者等效:
  • 0 0 1 1 *
  • 0 0 1 JAN *
在每年第一個月的第一天 (1 月 1 日) 凌晨 12:00 (24 小時制的 00:00) 執行。

時區

您可以在Google Cloud 控制台 (在「Create a job」(建立工作) 頁面中,從清單中選取「Timezone」(時區)),或在建立工作時透過 gcloud --time-zone 旗標,選取評估時間表的時區。

這個欄位的值必須是 tz 資料庫中使用的時區縮寫。預設時區為 UTC。

在某些時區,日光節約時間可能會導致工作意外執行或不執行。這是因為 Cloud Scheduler 是依據實際時間執行。如果某個時間點可能出現兩次 (例如時鐘往回撥),而您的工作排定在這個時間點執行,則排定的工作可能會出現執行異常。

如果工作需要非常特定的頻率,建議您選擇不採用日光節約時間的時區。具體來說,建議您為 Cloud Scheduler 採用世界標準時間,徹底避免這個問題。

替代工作格式

您可以使用更易於理解的時間規格格式 (稱為 groc),做為 cron 運算式的替代方案。舉例來說,有些週期性活動可能不適合使用 cron 指定,例如「每個月的第三個星期二」或「每兩週」(每 336 小時)。在這種情況下,您可以改用下列範例中的建構:

03 of month 12:34
1,3,4,7,11,18,29 of jan,jul 12:34
1st friday of quarter 9:00
1st,third monday of month 04:00
2nd,3rd tue,wed,thu of feb,aug 13:50
every 336 hours
every 48 hours
every 5 minutes
every 60 minutes on mon,wed
every day 09:00
every minute
every sun,tue,thu 9:00
every wed of december 00:00
first sunday of month 12:00
second,4th tue,thursday of 3rd month of quarter 18:30

使用 groc 指定工作排程時,必須使用 gcloud CLI,或直接向 Cloud Scheduler API 提出要求。

如要進一步瞭解語法,請參閱「定義 Cron 工作排程」。

後續步驟