תזמון משימות באמצעות 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 משימות מתוזמנות.

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

אפשר להגדיר את ההרשאה בדף 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 עם הבקשה, ולכן הן לא מנותבות לגרסאות אחרות.
  • אם אתם משתמשים ב קובץ הפצה, המשימות שלכם יכולות להיות מנותבות מחדש אם אותה כתובת 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 מתוזמנות במרווחי זמן חוזרים, ומצוינות באמצעות פורמט פשוט שדומה לאנגלית. אפשר להגדיר תזמון כך שהעבודה תרוץ כמה פעמים ביום, או בימים ובחודשים ספציפיים.

חלוקה למרווחי זמן קצרים מיום

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

  • מרווח זמן לסיום: מגדיר את הזמן שבין 'שעת הסיום' של עבודה לבין תחילת העבודה הבאה, כאשר 'שעת הסיום' היא השעה שבה העבודה מסתיימת או השעה שבה חל timeout. שירות 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]. אפשר להגדיר טווח זמן מותאם אישית או להשתמש באפשרות 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.

דוגמאות למרווחי זמן של שעת התחלה
הדוגמאות הבאות יעזרו לכם להבין איך להגדיר תזמונים של משימות שמשתמשים במרווח זמן להתחלה:
  • פועל כל 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.

      • דוגמה: 

      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

ציון ניסיונות חוזרים

אם בקשת 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.

בזמן הריצה של 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.