יצירת Task Handlers

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

כתיבת handler לבקשת משימה מסוג push

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

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

כשכותבים את הפונקציה לטיפול בשגיאות, חשוב להקפיד על ההנחיות הבאות:

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

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

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

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

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

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

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

קריאת כותרות הבקשות

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

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

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

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

אם בקשות הטיפול שלכם מוצאות אחת מהכותרות שמופיעות למעלה, הן יכולות לסמוך על כך שהבקשה היא בקשה של Task Queue.

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

כותרת תיאור
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

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