תזמון משימות באמצעות cron.yaml

שירות Cron של App Engine מאפשר להגדיר משימות מתוזמנות באופן קבוע שפועלות בזמנים מוגדרים או במרווחי זמן קבועים. המשימות האלה נקראות בדרך כלל משימות cron. משימות ה-cron האלה מופעלות אוטומטית על ידי שירות ה-Cron של App Engine. לדוגמה, אפשר להשתמש בזה כדי לשלוח אימייל עם דוח על בסיס יומי, לעדכן נתונים מסוימים במטמון כל 10 דקות או לעדכן נתוני סיכום מסוימים פעם בשעה.

משימת cron שולחת בקשת HTTP GET מתוזמנת לנקודת הקצה שצוינה באותה אפליקציה שבה מוגדרת משימת ה-cron. ה-handler של נקודת הקצה הזו מפעיל את הלוגיקה כשהוא נקרא.

אי אפשר להשתמש בשירות Cron של App Engine כדי לקרוא לנקודות קצה באינטרנט מחוץ לאפליקציית המארח של App Engine. אי אפשר להשתמש בו כדי לקרוא לנקודות קצה של App Engine מאפליקציות אחרות מלבד אפליקציית המארח.

בקשות של משימות Cron כפופות לאותן מגבלות כמו בקשות HTTP אחרות . באפליקציות חינמיות יכולות להיות עד 20 משימות מתוזמנות. באפליקציות בתשלום אפשר לתזמן עד 250 משימות.

כדי לפרוס או לעדכן תזמונים, צריך שיהיה לחשבון שלכם אחד מהתפקידים הבאים בניהול זהויות והרשאות גישה:

בעלים
עריכה
אדמין ב-Cloud Scheduler (roles/cloudscheduler.admin)

אפשר להגדיר את ההרשאה בדף IAM במסוף Google Cloud .

מידע על קובץ התצורה `cron`

בכל סביבות זמן הריצה, למעט Java, קובץ cron.yaml בתיקיית השורש של האפליקציה (לצד app.yaml) מגדיר משימות מתוזמנות לאפליקציה.

ב-Java, קובץ cron.yaml בספרייה WEB-INF של האפליקציה (לצד apppengine-web.xml) מגדיר משימות מתוזמנות לאפליקציה.

קובץ 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. בהגדרת משימה חייבים להיות url ו-schedule. אפשר גם לציין באופן אופציונלי description, timezone, target ו-retry_parameters:

url

שדה חובה. כתובת ה-URL באפליקציה שאליה רוצים ששירות Cron ישלח בקשות למשימות.

schedule

שדה חובה. הגדרת לוח הזמנים שבו רוצים שהעבודה תפעל, התחביר מפורט בהמשך.

description

אופציונלי. תיאור של משימת ה-cron, שמוצג במסוף Google Cloud .

timezone

אופציונלי. השם של אזור הזמן, או zoneinfo, שבו רוצים להשתמש לתזמון של העבודה. אם לא מציינים אזור זמן, התזמון מתבצע לפי UTC, שנקרא גם GMT.

target

אופציונלי. השם של שירות ספציפי באפליקציה. כשמציינים את target, שירות Cron מכוון את בקשת העבודה לשירות הזה באפליקציה. בקשות העבודה מנותבות לגרסאות בשירות שצוין שהוגדרו לתנועה. איך הבקשות מנותבות

שיקולים חשובים לגבי target:

אם הפעלתם פיצול תנועה, בקשות העבודה לא יפוצלו בין הגרסאות שהגדרתם:
- פיצול כתובות IP: בקשות לעבודות משירות Cron תמיד נשלחות מאותה כתובת IP, ולכן הן מנותבות לאותה גרסה בכל פעם.
- פיצול קובצי Cookie: בקשות לעיבוד משימות לא כוללות קובץ Cookie עם הבקשה, ולכן הן לא מנותבות לגרסאות אחרות.
אם אתם משתמשים ב קובץ dispatch, המשימות שלכם יכולות להיות מנותבות מחדש אם אותה כתובת URL מוגדרת גם ב-dispatch.yaml. לדוגמה, אם כתובת ה-URL של /tasks/hello_service2 מוגדרת בשני הקבצים הבאים, cron.yaml ו-dispatch.yaml, בקשות העבודה נשלחות אל service2, גם אם צוין target: service1:
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 שעות ביממה, החל ממרווח אחד אחרי שעת היצירה או העדכון של המשימה, וממתין למרווח שצוין בין כל משימה.
דוגמה: עבור לוח הזמנים every 5 minutes, העבודה מופעלת מדי יום במרווח של 5 דקות. אם מופע אחד של עבודה שפועל לפי התזמון הזה מסתיים בשעה 02:01, העבודה הבאה ממתינה 5 דקות ומתחילה שוב בשעה 02:06.
מרווח זמן להתחלה: הגדרה של מרווח זמן קבוע שבו שירות Cron יתחיל כל משימה. בניגוד למרווח הזמן של שעת הסיום, מרווח הזמן של שעת ההתחלה מפעיל כל משימה בלי קשר למועד שבו המשימה הקודמת מסתיימת או מסתיימת בגלל חוסר פעילות. אפשר להגדיר טווח זמן שבו רוצים שהמשימה תפעל, או להפעיל משימות 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:

End-time interval

‫[TYPE]: במרווחי זמן יומיים צריך לכלול את הקידומת every.
דוגמה: schedule: every 12 hours
‫[INTERVAL_VALUE]: ערך מסוג מספר שלם ויחידת הזמן המתאימה. הערכים התקפים ליחידת הזמן:
- minutes או mins
- hours
‫[INTERVAL_SCOPE]: לא רלוונטי. כדי להגדיר שעת התחלה ספציפית או טווח שעות שבו רוצים שהעבודות יפעלו, אפשר לעיין בתחביר של מרווח שעות התחלה או של מרווח בהתאמה אישית.

דוגמאות למרווחי זמן של סיום

הדוגמאות הבאות יעזרו לכם להבין איך להגדיר תזמונים של משימות שמשתמשים במרווח של שעת סיום:

הסקריפט ימתין 5 דקות אחרי הפריסה לפני ההפעלה הראשונה. אחרי שכל משימה מסתיימת, שירות Cron ממתין 5 דקות לפני הפעלת המשימה הבאה:
```
schedule: every 5 minutes
```
הסקריפט יפעל בפעם הראשונה 30 דקות אחרי הפריסה. אחרי שכל משימה מסתיימת, שירות Cron ממתין 30 דקות לפני שהוא מריץ את המשימה הבאה:
```
schedule: every 30 mins
```

מרווח זמן של שעת ההתחלה

‫[TYPE]: מרווחי זמן יומיים חייבים לכלול את הקידומת every.
דוגמה: schedule: every 12 hours
‫[INTERVAL_VALUE]: ערך מסוג מספר שלם ויחידת הזמן המתאימה. הערכים התקפים ליחידת הזמן:
- minutes או mins
- hours
‫[INTERVAL_SCOPE] מציין פסקה שמתאימה לערך [INTERVAL_VALUE]. אפשר להגדיר טווח זמן מותאם אישית או להשתמש באפשרות synchronized של 24 שעות.
- כוללים את פסוקית 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.

דוגמאות למרווחי זמן של שעת התחלה

הדוגמאות הבאות יעזרו לכם להבין איך להגדיר תזמונים של משימות שמשתמשים במרווח זמן להתחלה:

פועל כל 5 דקות בין השעות 10:00 ל-14:00, בכל יום:
```
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
```

קביעת ניסיונות חוזרים

אם בקשת handler של משימת cron מחזירה קוד סטטוס שלא נמצא בטווח 200-299 (כולל), App Engine מחשיב את המשימה הזו ככזו שנכשלה. כברירת מחדל, לא מתבצעים ניסיונות חוזרים של משימות שנכשלו. כדי לגרום למשימות שנכשלו לנסות שוב, צריך לכלול בלוק retry_parameters בקובץ ההגדרות.

הנה דוגמה לקובץ cron.yaml שמכיל משימת cron אחת שהוגדרה לניסיון חוזר עד חמש פעמים עם השהיה לפני ניסיון חוזר (backoff) ראשונית של 2.5 שניות שמוכפלת בכל פעם.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    job_retry_limit: 5
    min_backoff_seconds: 2.5
    max_doublings: 5

תחביר של ניסיונות חוזרים ב-Cron

פרמטרים של ניסיון חוזר מתוארים בטבלה הבאה.

רכיב	תיאור
`job_retry_limit`	מספר שלם שמייצג את המספר המקסימלי של ניסיונות חוזרים עבור משימת cron שנכשלה. הערך המינימלי הוא `0` והערך המקסימלי הוא `5`. אם מציינים גם את `job_age_limit`, מערכת App Engine מנסה שוב להריץ את משימת ה-cron עד שהיא מגיעה לשתי המגבלות. ערך ברירת המחדל של `job_retry_limit` הוא `0`.
`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

כדאי לוודא שהבקשות לכתובות ה-URL של cron מגיעות מ-App Engine ולא ממקור אחר. כדי לעשות את זה, אפשר לאמת את כותרת ה-HTTP ואת כתובת ה-IP של המקור של הבקשה:

בקשות מ-Cron Service יכללו את כותרת ה-HTTP הבאה:
```
"X-Appengine-Cron": "true"
```
הכותרת הזו וכותרות אחרות מוגדרות באופן פנימי על ידי App Engine. אם לקוח שולח את הכותרות האלה, הן מוסרות מהבקשה.
‫App Engine שולח בקשות Cron מכתובת ה-IP‏ 0.1.0.2. למשימות Cron שנוצרו בגרסאות ישנות יותר של gcloud (קודמות לגרסה 326.0.0), בקשות Cron יגיעו מ-0.1.0.1.

הערה: אם מגדירים חומת אש, צריך להגדיר כלל חומת אש לכתובת ה-IP‏ 0.1.0.2 או 0.1.0.1 כדי לאפשר לאפליקציה לקבל בקשות משירות Cron.

בזמן ריצה של Java, ב-Jetty או ב-Tomcat, אפשר לבצע את האימות הזה במסנן.

משך הבקשה הסתיים

הזמן הקצוב לתפוגה של בקשת cron הוא 60 דקות.

מידע נוסף על פסק זמן לתפוגת בקשה לפי סביבה וסוג שינוי גודל זמין במאמר בנושא בחירת סביבת App Engine.

העלאת משימות cron

כדי להעלות את משימות ה-cron, צריך לציין את cron.yaml כפרמטר בפקודת gcloud הבאה:

gcloud app deploy cron.yaml

מחיקת משימות cron

כדי למחוק את כל משימות ה-cron, משנים את הקובץ cron.yaml כך שיכיל רק את השורה הבאה:

cron:

תמיכה ב-Cron במסוף Google Cloud

אפשר לבדוק את משימות ה-cron המתוזמנות ב Google Cloud מסוף בדף Cron jobs.

אפשר גם להיכנס לדף היומנים כדי לראות מתי נוספו או הוסרו משימות cron.