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 點，工作會在上午 8 點執行。

  • 小時：表示工作在午夜後執行了多少小時 (向下取整至最接近的小時，因為剩餘分鐘數會顯示在 minute 欄位中)。午夜為 0，中午為 12。舉例來說，如果小時數設為 0，工作會在午夜時執行 (因為這是午夜後 0 小時)。

  • 當月日期：指出當月的日曆日期。舉例來說，如果當月第一天是星期五，1Cloud Scheduler 不支援以 L 代表當月最後一天。

  • 月份：指出月份。請指定月份編號，或以大寫字母指定月份名稱的前三個字母。例如 1 月的 1，或等效的 JAN。

  • 星期幾：顯示星期幾。舉例來說，星期一為 1，星期二為 2。0或 7 皆可表示星期日。以數字或大寫的星期名稱前三個字母指定星期幾 (例如 SUN 代表星期日)。

    • 除非其中一個欄位標示為「無限制」 (以星號 * 表示)，否則這個欄位會評估為包含 OR 的 day of the month 欄位。舉例來說，如果將「月份中的某一天」設為 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 * * * *：工作會在每半小時的前五分鐘執行 (整點和半點)。

略過範圍中的值

您可以指定在範圍中逐步執行的速率，藉此略過 range 中的值。這有時稱為使用步階函式 (或步階值或速率運算式)。方法是指定範圍，然後加上斜線 (/) 和要跳過範圍的速率。

您可以使用星號 (*) 表示欄位的所有值範圍。 使用星號時，範圍中的第一個值為：分鐘、小時和星期幾 (週日) 欄位為 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 點 (24 小時制為 00:00) 執行。
平日(週一至週五)
 以下會產生相同結果：
  • 0 0 * * 1-5
  • 0 0 * * MON-FRI
 每週一、二、三、四、五的 00:00 (24 小時制) 執行。
每週 以下會產生相同結果：
  • 0 0 * * 0
  • 0 0 * * 7
  • 0 0 * * SUN
 每週日 00:00 (以 24 小時制表示)。
每個月 0 0 1 * * 在每月第一天的凌晨 12:00 (24 小時制為 00:00) 執行。
每季 以下會產生相同結果：
  • 0 0 1 1,4,7,10 *
  • 0 0 1 JAN,APR,JUL,OCT *
 在每個季度的第一天凌晨 12 點 (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 運算式。

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

舉例來說，使用 Cron 指定某些週期性事件可能不太方便，例如「每個月的第三個星期二」。在這種情況下，您可以改用下列範例中的建構函式：

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

如要進一步瞭解語法，請參閱定義 Cron 工作時間表。

後續步驟