יצירת Task Handlers

בדף הזה מוסבר איך ליצור רכיב handler של משימות, שהוא הקוד שמטפל במשימת דחיפה. צריך לספק handler של בקשות כדי לעבד את המשימה. המיפוי מכתובת ה-URL של הבקשה ל-handler המתאים מוגדר בקובץapp.yamlשל השירות, בדיוק כמו כל handler אחר של בקשות. אתם יכולים להחליט איך למפות את בקשות המשימות ל-handler, ולכן אתם יכולים לארגן את ה-handlers של המשימות איך שאתם רוצים. אם האפליקציה מעבדת הרבה סוגים שונים של משימות, אתם יכולים להוסיף את כל ה-handlers לשירות אחד או להפיץ אותם בין כמה שירותים.

כתיבת handler לבקשות של משימות דחיפה

בתור, שירות תור המשימות יוצר כותרת HTTP ושולח אותה למכונה של שירות ה-worker שצוין ביעד של המשימה. בקשות של תור משימות נשלחות מכתובת ה-IP‏ 0.1.0.2.

אם ה-handler נמצא בשירות נפרד, הוא לא חייב להיות כתוב באותה שפה שבה נוצרה המשימה והוכנסה לתור.

כשכותבים את ה-handler, צריך לפעול לפי ההנחיות הבאות:

  • הקוד צריך להחזיר קוד סטטוס של HTTP בטווח 200-299 כדי לציין הצלחה. כל קוד אחר מצביע על כך שהמשימה נכשלה.

  • למשימות דחיפה יש מועד אחרון להשלמה שתלוי בסוג ההתאמה לעומס (scaling) של השירות שמריץ אותן. שירותי התאמה אוטומטית לעומס (automatic scaling) חייבים להסתיים תוך 10 דקות. שירותים עם התאמה ידנית ובסיסית של משאבים יכולים לפעול עד 24 שעות. אם ה-handler לא יעמוד במועד האחרון, שירות תור המשימות יניח שהמשימה נכשלה וינסה אותה שוב.

    כשזמן הביצוע של משימה מתקרב למועד האחרון, App Engine מעלה את השגיאה DeadlineExceededError (מהמודול google.appengine.runtime) לפני שהמועד האחרון מגיע, כדי שתוכלו לשמור את העבודה או לתעד את ההתקדמות שנעשתה.

  • ה-handler חייב להיות אידמפוטנטי. ‫Task Queue API של App Engine נועד לספק מסירה "לפחות פעם אחת". כלומר, אם משימה נוספה בהצלחה, App Engine יעביר אותה ל-handler לפחות פעם אחת. שימו לב שבמקרים נדירים, יכול להיות שיתבצעו כמה משימות, ולכן הקוד שלכם צריך לוודא שאין השפעות מזיקות להפעלה חוזרת.

תור המשימות משתמש בקוד ה-HTTP בתגובה של ה-handler כדי לקבוע אם המשימה הצליחה. התגובה מה-handler נראית רק לשירות תור משימות, ורק כדי לקבוע אם המשימה הצליחה. התור מתעלם מכל שאר השדות בתגובה. לאחר מכן, השירות מוחק את התשובה. האפליקציה שממנה הגיעו הנתונים לא מקבלת אף אחד מהנתונים. אם משימה נכשלת, שירות תור המשימות מנסה לבצע אותה שוב על ידי שליחת בקשה נוספת.

אפשר להעביר נתונים שסופקו על ידי המשתמש ל-handler בבקשה כמחרוזת שאילתה או כמטען ייעודי (payload) בגוף הבקשה. הוספת נתוני משתמשים מתוארת במאמר יצירת משימות. אם הבקשה כוללת נתונים, ה-handler צריך לדעת איך הם הוכנסו לבקשה. הקוד המדויק שבו משתמשים כדי לאחזר את הנתונים מהבקשה תלוי במסגרת האינטרנט הספציפית שבה אתם משתמשים.

כדי לבדוק handler של משימה, נכנסים כאדמינים ונכנסים לכתובת ה-URL של ה-handler בדפדפן.

קריאת כותרות של בקשות (request headers)

בקשת HTTP של משימה להעברה מכילה כותרות מיוחדות שמוגדרות על ידי App Engine, שמכילות מידע ספציפי למשימה שבו ה-handler יכול להשתמש.

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

בקשות מתור המשימות תמיד יכילו את הכותרות הבאות:

כותרת תיאור
X-Appengine-QueueName שם התור (אולי "default" לתור הדחיפה שמוגדר כברירת מחדל).
X-Appengine-TaskName שם המשימה, או מזהה ייחודי שנוצר על ידי המערכת אם לא צוין שם.
X-Appengine-TaskRetryCount מספר הפעמים שהמשימה הזו הופעלה מחדש. בניסיון הראשון, הערך הזה הוא 0. המספר הזה כולל ניסיונות שבהם המשימה נכשלה בגלל מחסור במכונות זמינות, ולא הגיעה לשלב הביצוע.
X-Appengine-TaskExecutionCount מספר הפעמים שהמשימה הזו נכשלה בעבר בשלב הביצוע. המספר הזה לא כולל כשלים שנובעים ממחסור במכונות זמינות.
X-Appengine-TaskETA זמן היעד לביצוע המשימה, בשניות מאז 1 בינואר 1970.

אם ה-request handler מוצא את אחת מהכותרות שרשומות למעלה, הוא יכול לסמוך על כך שהבקשה היא בקשה של תור משימות.

בנוסף, בקשות מתור המשימות יכולות להכיל את הכותרות הבאות:

כותרת תיאור
X-Appengine-TaskPreviousResponse קוד התגובה של HTTP מהניסיון הקודם.
X-Appengine-TaskRetryReason הסיבה לניסיון החוזר של המשימה.
X-Appengine-FailFast מציין שמשימה שפועלת נכשלת באופן מיידי אם אין מכונה זמינה.

אבטחת כתובות ה-URL של ה-task handler

אם משימה מבצעת פעולות רגישות (כמו שינוי נתונים), יכול להיות שתרצו לאבטח את כתובת ה-URL של ה-handler כדי למנוע ממשתמש חיצוני זדוני לקרוא לה ישירות. כדי למנוע ממשתמשים לגשת לכתובות ה-URL של המשימות, אתם יכולים להגביל את הגישה לאדמינים של App Engine. בקשות המשימות עצמן מונפקות על ידי App Engine, ותמיד יכולות לטרגט כתובת URL מוגבלת.

כדי להגביל כתובת URL, מוסיפים את הרכיב login: admin להגדרות של ה-handler בקובץ app.yaml.

לדוגמה:

handlers:
- url: /your-task
  script: worker.app
  login: admin

המאמרים הבאים