מאמר עזרה בנושא קובץ app.yaml ב-App Engine

מזהה אזור

‫REGION_ID הוא קוד מקוצר ש-Google מקצה על סמך האזור שבוחרים כשיוצרים את האפליקציה. הקוד לא תואם למדינה או למחוז, למרות שחלק ממזהי האזורים עשויים להיראות דומים לקודים נפוצים של מדינות ומחוזות. באפליקציות שנוצרו אחרי פברואר 2020, REGION_ID.r נכלל בכתובות URL של App Engine. באפליקציות קיימות שנוצרו לפני התאריך הזה, מזהה האזור הוא אופציונלי בכתובת ה-URL.

מידע נוסף על מזהי אזורים

אישור

Go Java Node.js PHP Python Ruby

מגדירים את ההגדרות של אפליקציית App Engine בקובץ ההגדרות app.yaml configuration file. בקובץ ההגדרות צריך לציין לפחות רשומה אחת של runtime.

לכל שירות באפליקציה יש קובץ app.yaml משלו, שמשמש כמתאר לפריסה שלו. קודם צריך ליצור את הקובץ app.yaml עבור השירות default, ורק אחר כך אפשר ליצור ולפרוס קבצים מסוג app.yaml עבור שירותים נוספים באפליקציה. מידע נוסף על מבנה של כמה שירותים באפליקציה זמין במאמר Structuring Web Services in App Engine.

תחביר

התחביר של app.yaml הוא פורמט YAML.

פורמט ה-YAML תומך בתגובות. שורה שמתחילה בתו סולמית (#) מוזנחת:

# This is a comment.

תבניות של כתובות URL ונתיבי קבצים משתמשות בתחביר של ביטויים רגולריים מורחבים של POSIX, לא כולל רכיבי איסוף ומחלקות איסוף. יש תמיכה בהפניות חוזרות להתאמות מקובצות (למשל \1), וגם בתוספים האלה של Perl: ‏ \w \W \s \S \d \D.

דוגמה

דוגמה לקובץ app.yaml:

runtime: python314

instance_class: F2

env_variables:
  BUCKET_NAME: "example-gcs-bucket"

handlers:
# Matches requests to /images/... to files in static/images/...
- url: /images
  static_dir: static/images

- url: /.*
  secure: always
  redirect_http_response_code: 301
  script: auto

בטבלה הבאה מופיעות דוגמאות ל-YAML של שדות זמינים בקובץ app.yaml:

זמן ריצה ורכיבים באפליקציה

רכיב	תיאור
app_engine_apis	זה שינוי אופציונלי. מגדירים את השדה הזה לערך true כדי להפעיל גישה לכל השירותים בחבילה עבור סביבות זמן ריצה מהדור השני. אם מגדירים את השדה הזה לערך true או false, הפריסות יצליחו רק אם ההגדרה app_engine_bundled_services לא צוינה. מומלץ להשתמש ב-app_engine_bundled_services כדי לציין את השירותים בחבילה שהאפליקציה שלכם דורשת. הגישה הזו מאפשרת שליטה מדויקת יותר ומשפרת את האבטחה על ידי צמצום החשיפה לשירותים לא נחוצים. בנוסף, הוא מוודא שהאפליקציה מקבלת עדכונים קריטיים לשירותים שהיא משתמשת בהם בפועל, וכך אפשר לתחזק אותה.
app_engine_bundled_services	זה שינוי אופציונלי. צריך להגדיר את השדה הזה כדי לאפשר גישה לשירותים ספציפיים בחבילה בסביבות זמן ריצה מהדור השני. אי אפשר להשתמש בהגדרה הזו אם הגדרתם את השדה app_engine_apis לערך true. מציינים את אחד מהשירותים הנתמכים הבאים בחבילה באמצעות ההגדרה הזו: זהות האפליקציה: app_identity_service Blobstore: ‏ blobstore יכולות: capability_service ‫Datastore: datastore_v3 תמונות: images מרחבי שמות: namespaces חיפוש: search נדחה: deferred אימייל: mail Memcache: memcache מודולים: modules תורי משימות: taskqueue אחזור כתובת URL: urlfetch משתמש: user לדוגמה: app_engine_bundled_services: - user - memcache בדוגמה הזו, האפליקציה יכולה להשתמש רק בשירותים המשולבים Datastore ו-Memcache.
build_env_variables	זה שינוי אופציונלי. אם אתם משתמשים בסביבת זמן ריצה שתומכת בחבילות buildpack, אתם יכולים להגדיר משתני סביבה של build בקובץ app.yaml. מידע נוסף זמין במאמר שימוש במשתני סביבת build.
default_expiration	זה שינוי אופציונלי. הגדרת תקופה גלובלית של ברירת מחדל למטמון עבור כל רכיבי ה-handler של קבצים סטטיים באפליקציה. אפשר גם להגדיר משך אחסון במטמון לרכיבי handler ספציפיים של קבצים סטטיים. הערך הוא מחרוזת של מספרים ויחידות, שמופרדים באמצעות רווחים. היחידות יכולות להיות d לימים, h לשעות, m לדקות ו-s לשניות. לדוגמה, "4d 5h" מגדיר את תפוגת המטמון ל-4 ימים ו-5 שעות אחרי שהקובץ מתבקש בפעם הראשונה. אם לא מציינים את הערך הזה, שרת הייצור מגדיר את התפוגה ל-10 דקות. דוגמה ל-Python: runtime: python314 default_expiration: "4d 5h" handlers: # ... מידע נוסף מופיע במאמר בנושא תפוגה של מטמון.
entrypoint	זה שינוי אופציונלי. הפקודה מחליפה את התנהגות ההפעלה שמוגדרת כברירת מחדל על ידי הפעלת הפקודה entrypoint כשהאפליקציה מופעלת. כדי שהאפליקציה תוכל לקבל בקשות HTTP, רכיב entrypoint צריך לכלול פקודה שמפעילה שרת אינטרנט שמקשיב ביציאה 8080. אם לא מציינים entrypoint עבור סביבת זמן הריצה של Python, ‏ App Engine מגדיר ומפעיל את שרת האינטרנט Gunicorn. מידע נוסף זמין במאמר בנושא הפעלת אפליקציות.
env_variables	זה שינוי אופציונלי. אפשר להגדיר משתני סביבה בקובץ app.yaml כדי שהם יהיו זמינים לאפליקציה. חשוב לוודא שהמפתח במשתני הסביבה תואם לביטוי '[a-zA-Z_][a-zA-Z0-9_]*' (מתחיל באות או ב-'_' ואחריו כל תו אלפאנומרי או '_'). משתני סביבה שמתחילים בקידומת GAE שמורים לשימוש המערכת ואסור להשתמש בהם בקובץ app.yaml. ב-Python, המשתנים האלה זמינים במילון os.environ: env_variables: DJANGO_SETTINGS_MODULE: "myapp.settings" אפשר גם לעיין ברשימה של משתני סביבת זמן ריצה שלא ניתן להחליף.
error_handlers	זה שינוי אופציונלי. משמש להגדרת דפי שגיאה בהתאמה אישית שמוחזרים עבור סוגים שונים של שגיאות. האלמנט הזה יכול להכיל את האלמנטים הבאים: error_code אופציונלי. הערך error_code יכול להיות אחד מהערכים הבאים: over_quota מציין שהאפליקציה חרגה ממכסת משאבים timeout המודעה תוצג אם יגיע מועד סיום לפני שתתקבל תשובה מהאפליקציה. הפרמטר error_code הוא אופציונלי. אם לא מציינים אותו, הקובץ שצוין הוא תגובת השגיאה שמוגדרת כברירת מחדל באפליקציה. file כל רשומה בקובץ מציינת קובץ סטטי שצריך להציג במקום תגובת השגיאה הגנרית. אם מציינים רכיב file בלי רכיב error_code תואם, הקובץ הסטטי יהיה דף השגיאה שמוגדר כברירת מחדל לאפליקציה. אזהרה: חשוב לוודא שהנתיב לקובץ תגובת השגיאה לא חופף לנתיבים של ה-handler של הקבצים הסטטיים. הנתונים של השגיאה המותאמת אישית צריכים להיות קטנים מ-10 קילובייט. דוגמה error_handlers: - file: default_error.html - error_code: over_quota file: over_quota.html
handlers	זה שינוי אופציונלי. רשימה של תבניות URL ותיאורים של אופן הטיפול בהן. ‫App Engine יכול לטפל בכתובות URL על ידי הפעלת קוד האפליקציה, או על ידי הצגת קבצים סטטיים שהועלו עם הקוד, כמו תמונות, CSS או JavaScript. מידע על התחביר של רכיבי Handler ותתי-רכיבים
inbound_services	זה שינוי אופציונלי. האפליקציות צריכות להפעיל את השירותים האלה כדי שיוכלו לקבל בקשות נכנסות. כדי להפעיל את השירות באפליקציה, צריך לכלול קטע inbound_services בקובץ app.yaml. warmup הפעלת בקשות בשלב ההפעלה של האפליקציה. הגדרת בקשות לחימום לדוגמה: inbound_services: - warmup
instance_class	זה שינוי אופציונלי. סוג האירוע של השירות הזה. הערכים הבאים זמינים בהתאם להתאמה של השירות: שינוי גודל אוטומטי F1, F2, F4, F4_1G ברירת מחדל: F1 אופציונלי: אפשר להשתמש ברכיב automatic_scaling כדי לשנות את הגדרות ברירת המחדל של התאמה אוטומטית לעומס, כמו מספר המכונות המינימלי והמקסימלי, זמן האחזור והחיבורים המקבילים. הערה: אם הערך של instance_class מוגדר כ-F2 או יותר, אפשר לבצע אופטימיזציה של המופעים על ידי הגדרת max_concurrent_requests לערך גבוה יותר מברירת המחדל 10. כדי לקבוע את הערך האופטימלי, צריך להגדיל אותו בהדרגה ולעקוב אחרי הביצועים של האפליקציה. התאמה אוטומטית של נפח האחסון והתאמה ידנית של נפח האחסון B1, B2, B4, B4_1G, B8 ברירת מחדל: B2 במקרים של מחלקות בסיסיות ומחלקות ידניות של מופעים, צריך לציין את הרכיב basic_scaling או את הרכיב manual_scaling.
runtime	חובה. השם של סביבת זמן הריצה שבה האפליקציה שלכם משתמשת. לדוגמה, כדי לציין את סביבת זמן הריצה, משתמשים ב: runtime: python314
service	חובה אם יוצרים שירות. אופציונלי לשירות default. לכל שירות ולכל גרסה צריך להיות שם. שם יכול להכיל מספרים, אותיות ומקפים. האורך המשולב של VERSION-dot-SERVICE-dot-PROJECT_ID, כאשר VERSION הוא שם הגרסה, SERVICE הוא שם השירות ו-PROJECT_ID הוא מזהה הפרויקט, לא יכול להיות יותר מ-63 תווים, והוא לא יכול להתחיל או להסתיים במקף. צריך לבחור שם ייחודי לכל שירות ולכל גרסה. אל תשתמשו באותם שמות בשירותים ובגרסאות שונים. דוגמה: service: service-name
service_account	זה שינוי אופציונלי. האלמנט service_account מאפשר לציין חשבון שירות ספציפי לגרסה כזהות של הגרסה. חשבון השירות שצוין משמש לגישה לשירותים אחרים Google Cloud ולביצוע משימות. דוגמה: service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
vpc_access (תצוגה מקדימה)	זה שינוי אופציונלי. מגדירים Direct VPC egress בשירות, כדי שהאפליקציה תוכל לשלוח בקשות למשאבים פנימיים ברשת ה-VPC. ההגדרה הזו כוללת את השדות הבאים: network_interface מכיל הגדרות של ממשק רשת לשימוש ב-Direct VPC egress. network השם של רשת ה-VPC שבה רוצים להשתמש עבור Direct VPC egress. subnet השם של רשת המשנה ב-VPC שבה רוצים להשתמש עבור Direct VPC egress. tags אופציונלי. רשימה של תגי רשת לשיוך למופעים של השירות לשימוש בכללי חומת אש ובמדיניות ניתוב. vpc_egress אופציונלי. המדיניות קובעת את אופן הניתוב של תעבורה יוצאת. בשדה הזה אפשר להזין את הגדרות התצורה הבאות: private-ranges-only ברירת מחדל. רק תנועה לכתובות IP פנימיות מנותבת דרך רשת ה-VPC. תעבורת האינטרנט משתמשת בנתיב ברירת המחדל של App Engine. all-traffic כל הבקשות היוצאות מנותבות דרך רשת ה-VPC. מידע נוסף על הגדרת Direct VPC egress זמין במאמר התחברות לרשת VPC באמצעות Direct VPC egress. דוגמה vpc_access: network_interface: network: direct-vpc-network subnet: direct-vpc-subnetwork tags: - my-tag1 - my-tag2 vpc_egress: all-traffic
vpc_access_connector	זה שינוי אופציונלי. הכלי מגדיר את האפליקציה כך שתשתמש במחבר של חיבור לרשת (VPC) מאפליקציית serverless, וכך האפליקציה תוכל לשלוח בקשות למשאבים פנימיים ברשת ה-VPC. מידע נוסף זמין במאמר התחברות לרשת VPC. name ייצוג מילולי של מחרוזת. מציינים את השם המלא של המחבר של הגישה ל-VPC מאפליקציית serverless במירכאות: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME" egress_setting אופציונלי. ערך ברירת המחדל הוא private-ranges-only. הערך של egress_setting יכול להיות אחד מהערכים הבאים: private-ranges-only ברירת מחדל. בקשות לכתובות IP פנימיות נשלחות דרך מחבר של חיבור לרשת (VPC) מאפליקציית serverless אל רשת ה-VPC המחוברת. בקשות לכתובות IP חיצוניות נשלחות לאינטרנט הציבורי. all-traffic כל הבקשות נשלחות דרך מחבר הגישה ל-VPC מאפליקציית serverless אל רשת ה-VPC המחוברת. דוגמה vpc_access_connector: name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME" egress_setting: all-traffic

רכיב Handlers

רכיב handlers מספק רשימה של תבניות כתובות URL ותיאורים של אופן הטיפול בהן. ‫App Engine יכול לטפל בכתובות URL על ידי הפעלת קוד האפליקציה, או על ידי הצגת קבצים סטטיים שהועלו עם הקוד, כמו תמונות, CSS או JavaScript.

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

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

רכיב	תיאור
auth_fail_action	כדי להשתמש ברכיב הזה, צריך להפעיל את Users API על ידי הגדרת ההגדרה user ברשימה app_engine_bundled_services או להגדיר את השדה app_engine_apis לערך true. זה שינוי אופציונלי. מתאר את הפעולה שמתבצעת כשאלמנט login מצוין עבור handler והמשתמש לא מחובר לחשבון. יש לו שני ערכים אפשריים: redirect ברירת מחדל. המשתמש מופנה לדף הכניסה של Google, או /_ah/login_required אם נעשה שימוש באימות OpenID. המשתמש מופנה חזרה לכתובת ה-URL של האפליקציה אחרי שהוא נכנס לחשבון או יוצר חשבון. unauthorized הבקשה נדחית עם קוד סטטוס HTTP 401 והודעת שגיאה. אם האפליקציה צריכה להתנהג אחרת, היא יכולה להטמיע את הטיפול בהתחברות של המשתמשים. לדוגמה, דרישה להתחברות לספרייה /profile/ או להתחברות אדמין לספרייה /admin/. מידע נוסף מופיע במאמר בנושא Users API. אתם יכולים להגדיר את ה-handler כך שיסרב להעניק גישה לכתובות URL מוגנות כשהמשתמש לא מחובר, במקום להפנות אותו לדף הכניסה. כדי לעשות את זה, מוסיפים auth_fail_action: unauthorized להגדרות של ה-handler.
expiration	זה שינוי אופציונלי. משך הזמן שבו שרתי proxy ודפדפנים צריכים לשמור במטמון קובץ סטטי שמועבר על ידי ה-handler הזה. הערך הוא מחרוזת של מספרים ויחידות, שמופרדים באמצעות רווחים. היחידות יכולות להיות d לימים, h לשעות, m לדקות ו-s לשניות. לדוגמה, ‫"4d 5h" מגדיר את תפוגת המטמון ל-4 ימים ו-5 שעות אחרי הבקשה הראשונה לקובץ. אם לא מציינים ערך, המערכת משתמשת בערך default_expiration של האפליקציה. פרטים נוספים מופיעים במאמר בנושא תפוגה של מטמון.
http_headers	זה שינוי אופציונלי. אתם יכולים להגדיר כותרות HTTP לתגובות של קובץ סטטי או של רכיבי handler של ספריות. אם אתם צריכים להגדיר כותרות HTTP במעבדי script, עליכם לעשות זאת בקוד של האפליקציה. מידע על כותרות תגובה שמשפיעות על שמירה במטמון מופיע במאמר שמירה במטמון של תוכן סטטי. מידע נוסף על כותרות ספציפיות ל-App Engine זמין במאמר כותרות של בקשות ותגובות. דוגמה handlers: - url: /images static_dir: static/images http_headers: X-Foo-Header: foo X-Bar-Header: bar value vary: Accept-Encoding # ... תמיכה ב-CORS שימוש חשוב אחד בתכונה הזו הוא תמיכה בשיתוף משאבים בין מקורות (CORS), כמו גישה לקבצים שמתארחים באפליקציית App Engine אחרת. לדוגמה, יכול להיות שיש לכם אפליקציית משחקים mygame.uc.r.appspot.com שניגשת לנכסים שמארח myassets.uc.r.appspot.com. עם זאת, אם mygame מנסה לבצע XMLHttpRequest JavaScript אל myassets, הפעולה לא תצליח אלא אם ה-handler של myassets יחזיר כותרת תגובה Access-Control-Allow-Origin: שמכילה את הערך http://mygame.uc.r.appspot.com. כך אפשר לגרום ל-handler של קובץ סטטי להחזיר את הערך הנדרש של כותרת התגובה: handlers: - url: /images static_dir: static/images http_headers: Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com # ... טיפ: כדי לתת לכולם גישה לנכסים, אפשר להשתמש בתו הכללי '*' במקום ב-https://mygame.uc.r.appspot.com.
login	כדי להשתמש ברכיב הזה, צריך להפעיל את Users API על ידי הגדרת ההגדרה user ברשימה app_engine_bundled_services או להגדיר את השדה app_engine_apis לערך true. זה שינוי אופציונלי. ההגדרה קובעת אם המטפל בכתובות ה-URL דורש שהמשתמש יהיה מחובר. לרכיב הזה יש שלושה ערכים אפשריים: optional ברירת מחדל. לא נדרשת כניסה של המשתמש. required אם המשתמש נכנס לחשבון, ה-handler ממשיך כרגיל. אחרת, הפעולה שצוינה ב-auth_fail_action תתבצע. admin בדומה ל-required, הפעולה auth_fail_action מתבצעת אם המשתמש לא מחובר לחשבון. בנוסף, אם המשתמש לא אדמין באפליקציה, תוצג לו הודעת שגיאה בלי קשר להגדרה של auth_fail_action. אם המשתמש הוא אדמין, מתבצעת פעולה. כשמטפל בכתובות URL עם הגדרה של login שונה מ-optional מתאים לכתובת URL, המטפל בודק קודם אם המשתמש נכנס לאפליקציה באמצעות אפשרות האימות שלה. אם לא, כברירת מחדל, המשתמש מופנה לדף הכניסה. אפשר גם להשתמש ב-auth_fail_action כדי להגדיר את האפליקציה כך שהיא פשוט תדחה בקשות לטיפול ממשתמשים שלא עברו אימות כמו שצריך, במקום להפנות את המשתמש לדף הכניסה. הערה: גם בקשות פנימיות שבהן App Engine מגדיר כותרות מיוחדות מתאימות של X-Appengine, עומדות בדרישה של הגבלת הכניסה admin. לדוגמה, משימות מתוזמנות cron עומדות בהגבלה admin, כי App Engine מגדיר כותרת HTTP‏ X-Appengine-Cron: true בבקשות המתאימות. עם זאת, הבקשות לא יעמדו בדרישות של required הגבלת הכניסה, כי משימות מתוזמנות של cron לא מופעלות בתור משתמש כלשהו.
mime_type	זה שינוי אופציונלי. אם מציינים סוג MIME, כל הקבצים שמוצגים על ידי רכיב ה-handler הזה יוצגו באמצעות סוג ה-MIME שצוין. אם לא מציינים סוג MIME, הוא ייגזר מסיומת שם הקובץ. אם מעלים את אותו קובץ עם כמה תוספים, התוסף שמתקבל יכול להיות תלוי בסדר שבו בוצעו ההעלאות. מידע נוסף על סוגי מדיה אפשריים של MIME זמין באתר MIME Media Types של IANA.
redirect_http_response_code	זה שינוי אופציונלי. ההגדרה redirect_http_response_code משמשת עם ההגדרה secure כדי להגדיר את קוד התגובה של תגובת HTTP שמוחזר כשמבצעים הפניה אוטומטית שנדרשת בגלל האופן שבו ההגדרה secure מוגדרת. הרכיב redirect_http_response_code יכול לקבל את הערכים האפשריים הבאים: 301 קוד התגובה הועבר לצמיתות. 302 נמצא קוד תגובה. 303 ראו קוד תגובה אחר. 307 קוד תגובה של הפניה אוטומטית זמנית. כשבקשת משתמש מופנית מחדש, קוד הסטטוס של HTTP מוגדר לערך של הפרמטר redirect_http_response_code. אם הפרמטר לא קיים, יוחזר קוד 302.
script	זה שינוי אופציונלי. מציין שהבקשות לטיפול הספציפי צריכות להיות מיועדות לאפליקציה. הערך היחיד שמתקבל עבור רכיב script הוא auto, כי כל התנועה מוגשת באמצעות פקודת נקודת הכניסה. כדי להשתמש ב-handlers סטטיים, לפחות אחד מה-handlers צריך להכיל את השורה script: auto או להגדיר רכיב entrypoint כדי שהפריסה תצליח.
secure	זה שינוי אופציונלי. כל רכיב handler של כתובת URL יכול להשתמש בהגדרה secure, כולל רכיבי handler של קבצים סטטיים. לרכיב secure יש את הערכים האפשריים הבאים: optional גם בקשות HTTP וגם בקשות HTTPS עם כתובות URL שתואמות ל-handler מצליחות ללא הפניות אוטומטיות. האפליקציה יכולה לבדוק את הבקשה כדי לקבוע באיזה פרוטוקול נעשה שימוש, ולהגיב בהתאם. זוהי ברירת המחדל אם לא מציינים secure עבור רכיב handler. never בקשות לכתובת URL שתואמת ל-handler הזה שמשתמשות ב-HTTPS מופנות אוטומטית לכתובת URL מקבילה מסוג HTTP. כשבקשת HTTPS של משתמש מופנית מחדש כבקשת HTTP, פרמטרים של שאילתה מוסרים מהבקשה. כך נמנע מצב שבו משתמש שולח בטעות נתוני שאילתה דרך חיבור לא מאובטח, במקום דרך חיבור מאובטח. always בקשות לכתובת URL שתואמת ל-handler הזה שלא משתמשות ב-HTTPS מופנות אוטומטית לכתובת ה-URL של HTTPS עם אותו נתיב. פרמטרים של שאילתה נשמרים להפניה האוטומטית. דוגמה ל-Python handlers: - url: /youraccount/.* secure: always script: auto כדי לטרגט גרסה ספציפית של האפליקציה באמצעות הדומיין REGION_ID.r.appspot.com, מחליפים את הנקודות שמפרידות בדרך כלל בין רכיבי תת-הדומיין של כתובת ה-URL במחרוזת -dot-, לדוגמה: https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com כדי להשתמש בדומיינים מותאמים אישית עם HTTPS, קודם צריך להפעיל ולהגדיר אישורי SSL עבור הדומיין הזה. הכניסה לחשבונות Google והיציאה מהם מתבצעות תמיד באמצעות חיבור מאובטח, ללא קשר לאופן שבו כתובות ה-URL של האפליקציה מוגדרות.
static_dir	זה שינוי אופציונלי. הנתיב לספרייה שמכילה את הקבצים הסטטיים, מתיקיית הבסיס של האפליקציה. כל מה שמופיע אחרי סוף התבנית url שזוהתה מתווסף ל-static_dir כדי ליצור את הנתיב המלא לקובץ המבוקש. כל קובץ בספרייה הסטטית מוגש באמצעות סוג ה-MIME שתואם לסיומת של שם הקובץ, אלא אם הוא מוחלף על ידי ההגדרה mime_type של הספרייה. כל הקבצים בספרייה שצוינה מועלים כקבצים סטטיים, ואי אפשר להריץ אף אחד מהם כסקריפטים. לדוגמה: handlers: # All URLs beginning with /stylesheets are treated as paths to # static files in the stylesheets/ directory. - url: /stylesheets static_dir: stylesheets # ...
static_files	זה שינוי אופציונלי. ה-handler של תבנית קובץ סטטי משייך תבנית URL לנתיבים לקבצים סטטיים שהועלו עם האפליקציה. הביטוי הרגולרי של תבנית כתובת ה-URL יכול להגדיר קיבוצים של ביטויים רגולריים שישמשו ליצירת נתיב הקובץ. אפשר להשתמש בזה במקום ב-static_dir כדי למפות קבצים ספציפיים במבנה של ספרייה בלי למפות את כל הספרייה. לדוגמה: handlers: # All URLs ending in .gif .png or .jpg are treated as paths to # static files in the static/ directory. The URL pattern is a # regular expression, with a grouping that is inserted into the # path to the file. - url: /(.*\.(gif|png|jpg))$ static_files: static/\1 upload: static/.*\.(gif|png|jpg)$ # ... קבצים סטטיים לא יכולים להיות זהים לקובצי קוד אפליקציה.
upload	זה שינוי אופציונלי. ביטוי רגולרי שתואם לנתיבי הקבצים של כל הקבצים שרכיב ה-handler הזה יפנה אליהם. הפעולה הזו נדרשת כי המטפל לא יכול לקבוע אילו קבצים בספריית האפליקציה תואמים לדפוסי url ו-static_files שצוינו. קבצים סטטיים מועלים ומטופלים בנפרד מקבצי האפליקציה. בדוגמה שלמעלה, יכול להיות שנעשה שימוש בתבנית upload הבאה: archives/(.*)/items/(.*)
url	אלמנט חובה ב-handlers. תבנית ה-URL, כביטוי רגולרי שיכול להכיל קיבוצים. לדוגמה: הביטוי /profile/(.*)/(.*) יתאים לכתובת ה-URL /profile/edit/manager וישתמש בביטויים edit ו-manager כקיבוץ הראשון והשני. יש כמה הבדלים בהתנהגות של תבנית כתובת ה-URL כשמשתמשים בה עם הרכיבים הבאים: static_dir משתמש בקידומת של כתובת URL. תבנית הביטוי הרגולרי לא צריכה לכלול קיבוצים כשמשתמשים בה עם הרכיב static_dir. כל כתובות ה-URL שמתחילות בקידומת הזו מטופלות על ידי רכיב ה-handler הזה, באמצעות החלק של כתובת ה-URL שאחרי הקידומת כחלק מנתיב הקובץ. static_files ה-handler של תבנית קובץ סטטי משייך תבנית URL לנתיבים לקבצים סטטיים שהועלו עם האפליקציה. הביטוי הרגולרי של תבנית כתובת ה-URL יכול להגדיר קיבוצים של ביטויים רגולריים שישמשו ליצירת נתיב הקובץ. אפשר להשתמש בזה במקום ב-static_dir כדי למפות קבצים ספציפיים במבנה של ספרייה בלי למפות את כל הספרייה.

שינוי גודל של אלמנטים

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

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

רכיב	תיאור
automatic_scaling	זה שינוי אופציונלי. רלוונטי רק לאפליקציות שמשתמשות בסוג המופע F1 ומעלה. מציינים את הרכיב הזה כדי לשנות את הגדרות ברירת המחדל של התאמה אוטומטית לעומס (automatic scaling), כמו הגדרת רמות מינימום ומקסימום למספר המכונות, זמן טעינה, וחיבורים בו-זמנית לשירות. האלמנט הזה יכול להכיל את האלמנטים הבאים: max_instances אופציונלי. מציינים ערך בין 0 ל-2147483647, כאשר אפס משבית את ההגדרה. הערה: בפרויקטים חדשים שייווצרו אחרי מרץ 2025, App Engine יגדיר את ברירת המחדל של מספר המופעים המקסימלי לפריסות בסביבה רגילה ל-20. השינוי הזה לא משפיע על אפליקציות קיימות. כדי לשנות את ברירת המחדל, מציינים ערך חדש בין 0 ל-2147483647 ומפעילים גרסה חדשה או מפעילים מחדש גרסה קיימת. כדי להשבית את הגדרת ברירת המחדל של מספר המופעים המקסימלי, מציינים את הערך המקסימלי המותר 2147483647. הפרמטר הזה מציין את המספר המקסימלי של מופעים ש-App Engine יכול ליצור לגרסה הזו של המודול. כדאי להשתמש בזה כדי להגביל את העלויות של מודול. min_instances אזהרה: כדי שהתכונה הזו תפעל כמו שצריך, צריך לוודא שבקשות לחימום מראש מופעלות ושבקשות החימום מראש מטופלות באפליקציה. הערה: ההגדרה הזו רלוונטית רק אם הגרסה של האפליקציה שמוגדרת בקובץ app.yaml הזה מוגדרת לקבל תנועה. מידע נוסף על ניתוב תנועה לגרסאות שונות של אפליקציה זמין במאמר בנושא פיצול תנועה. אופציונלי. מספר המופעים המינימלי ש-App Engine צריך ליצור לגרסת המודול הזו. המופעים האלה מציגים תנועה כשהבקשות מגיעות, וממשיכים להציג תנועה גם כשמופעים נוספים מופעלים לפי הצורך כדי לטפל בתנועה. מציינים ערך בין 0 ל-1,000. אפשר להגדיר את הפרמטר לערך 0 כדי לאפשר שינוי קנה מידה ל-0 מופעים, וכך להפחית את העלויות כשלא מתבצעות בקשות. חשוב לדעת שאתם מחויבים על מספר המקרים שצוין, בין אם הם מקבלים תנועה ובין אם לא. max_idle_instances זה שינוי אופציונלי. המספר המקסימלי של מופעים לא פעילים ש-App Engine צריך לשמור לגרסה הזו. צריך לציין ערך בין 1 ל-1,000. אם לא מציינים ערך, ערך ברירת המחדל הוא automatic, כלומר, App Engine ינהל את מספר המופעים הלא פעילים. חשוב לזכור: ערך מקסימלי גבוה יותר יקטין את מספר המכונות הווירטואליות הלא פעילות בצורה הדרגתית יותר כשרמות העומס יחזרו למצב נורמלי אחרי עלייה חדה. השיטה הזו עוזרת לאפליקציה לשמור על ביצועים יציבים גם כשיש תנודות בעומס הבקשות, אבל היא גם מגדילה את מספר המופעים הלא פעילים (ואת עלויות ההפעלה שנובעות מכך) בתקופות של עומס כבד. הגדרת ערך מקסימלי נמוך מאפשרת לשמור על עלויות הפעלה נמוכות, אבל עלולה לפגוע בביצועים במקרים של עומסי תנועה משתנים. הערה: כשחוזרים לרמות רגילות אחרי עלייה פתאומית בעומס, יכול להיות שמספר המקרים הלא פעילים יעלה באופן זמני על המספר המקסימלי שהגדרתם. עם זאת, לא נחייב אתכם על יותר מקרים מהמספר המקסימלי שציינתם. min_idle_instances אזהרה: כדי שהתכונה הזו תפעל כמו שצריך, צריך לוודא שבקשות לחימום מראש מופעלות ושבקשות החימום מראש מטופלות באפליקציה. הערה: ההגדרה הזו רלוונטית רק אם הגרסה של האפליקציה שמוגדרת בקובץ app.yaml הזה מוגדרת לקבל תנועה. מידע נוסף על ניתוב תנועה לגרסאות שונות של אפליקציה זמין במאמר בנושא פיצול תנועה. אופציונלי: מספר המופעים הנוספים שיופעלו ויהיו מוכנים לשרת תנועה לגרסה הזו. ‫App Engine מחשב את מספר המופעים שנדרשים כדי לטפל בתנועה הנוכחית של האפליקציה על סמך הגדרות קנה המידה, כמו target_cpu_utilization ו-target_throughput_utilization. ההגדרה min_idle_instances מציינת את מספר המופעים להפעלה בנוסף למספר המחושב הזה. לדוגמה, אם App Engine מחשב שצריך 5 מכונות כדי לטפל בתעבורה, והערך של min_idle_instances הוא 2, ‏ App Engine יפעיל 7 מכונות (5, לפי החישוב על סמך התעבורה, ועוד 2 לפי min_idle_instances). שימו לב: אתם מחויבים על מספר המופעים שצוין, בין אם הם מקבלים תנועה ובין אם לא. חשוב לזכור: ערך מינימלי נמוך עוזר לשמור על עלויות ההפעלה נמוכות בתקופות של חוסר פעילות, אבל המשמעות היא שפחות מופעים עשויים להיות זמינים באופן מיידי כדי להגיב לעלייה פתאומית בעומס. ערך מינימלי גבוה מאפשר לכם להכין את האפליקציה לעליות חדות ומהירות בעומס הבקשות. ‫App Engine שומר על מספר מינימלי של מופעים שפועלים כדי לטפל בבקשות נכנסות. תחויבו על מספר המקרים שצוין, בין אם הם מטפלים בבקשות ובין אם לא. אם מגדירים מספר מינימלי של מופעים לא פעילים, לזמן האחזור של בקשות בהמתנה תהיה השפעה פחותה על ביצועי האפליקציה. target_cpu_utilization אופציונלי. מציינים ערך בין 0.5 ל-0.95. ערך ברירת המחדל הוא 0.6. הפרמטר הזה מציין את סף השימוש במעבד שמעליו יופעלו מופעים חדשים כדי לטפל בתנועה. כך אפשר לאזן בין ביצועים לעלות: ערכים נמוכים משפרים את הביצועים ומגדילים את העלות, וערכים גבוהים מפחיתים את הביצועים אבל גם את העלות. לדוגמה, ערך של 0.7 אומר שמופעים חדשים יופעלו אחרי ששימוש המעבד יגיע ל-70%. target_throughput_utilization אופציונלי. מציינים ערך בין 0.5 ל-0.95. ערך ברירת המחדל הוא 0.6. המאפיין הזה משמש עם max_concurrent_requests כדי לציין מתי מופעלת מכונה וירטואלית חדשה בגלל בקשות מקבילות. כאשר מספר הבקשות בו-זמנית מגיע לערך ששווה ל-max_concurrent_requests כפול target_throughput_utilization, מתזמן המשימות מנסה להפעיל מופע חדש. max_concurrent_requests זה שינוי אופציונלי. מספר הבקשות המקבילות שמופע של התאמה אוטומטית לעומס יכול לקבל לפני שהמתזמן יוצר מופע חדש (ברירת מחדל: 10, מקסימום: 1,000). משמש עם target_throughput_utilization כדי לציין מתי מופעלת מכונה וירטואלית חדשה בגלל בקשות מקבילות. כאשר מספר הבקשות בו-זמנית מגיע לערך ששווה ל-max_concurrent_requests כפול target_throughput_utilization, מתזמן המשימות מנסה להפעיל מופע חדש. מומלץ לא להגדיר את max_concurrent_requests לערך נמוך מ-10 אלא אם יש צורך בשימוש בשרשור יחיד. ערך נמוך מ-10 עלול לגרום ליצירה של יותר מופעים ממה שצריך לאפליקציה בטוחה לשימוש עם שרשורים, וזה עלול להוביל לעלויות מיותרות. אם ההגדרה הזו גבוהה מדי, יכול להיות שזמן האחזור של ה-API יתארך. שימו לב: יכול להיות שהמתזמן ייצור מופע חדש לפני שיושג המספר המקסימלי בפועל של בקשות. max_pending_latency כמות הזמן המקסימלית ש-App Engine צריך לאפשר לבקשה להמתין בתור להמתנה לפני הפעלת מופעים נוספים לטיפול בבקשות, כדי לצמצם את זמן האחזור של בקשות בהמתנה. כשמגיעים לסף הזה, המערכת מזהה שצריך להגדיל את הקיבולת, וכתוצאה מכך מספר המופעים גדל. אם לא מציינים ערך, ערך ברירת המחדל הוא automatic. המשמעות היא שבקשות יכולות להישאר בתור ההמתנה עד 10 שניות, שהוא זמן ההמתנה המקסימלי לבקשה, לפני שמופעלות התחלות חדשות של מופעים. ערך נמוך של המקסימום אומר שמערכת App Engine תתחיל מופעים חדשים מוקדם יותר לבקשות בהמתנה, מה שישפר את הביצועים אבל יעלה את עלויות ההפעלה. ערך מקסימלי גבוה אומר שהמשתמשים עלולים לחכות יותר זמן עד שהבקשות שלהם יטופלו (אם יש בקשות בהמתנה ואין מופעים לא פעילים שיכולים לטפל בהן), אבל העלות של הפעלת האפליקציה תהיה נמוכה יותר. min_pending_latency רכיב אופציונלי שאפשר להגדיר כדי לציין את משך הזמן המינימלי ש-App Engine צריך לאפשר לבקשה להמתין בתור להמתנה לפני הפעלת מופע חדש לטיפול בה. ציון ערך יכול להוריד את עלויות ההפעלה, אבל להאריך את הזמן שבו המשתמשים צריכים לחכות עד שהבקשות שלהם יטופלו. באפליקציות בחינם, ערך ברירת המחדל הוא 500ms. באפליקציות בתשלום, ערך ברירת המחדל הוא 0. האלמנט הזה פועל יחד עם האלמנט max_pending_latency כדי לקבוע מתי App Engine יוצר מופעים חדשים. אם יש בקשות בהמתנה בתור: אם מספר הבקשות יהיה נמוך מ-min_pending_latency שציינתם, לא ייווצרו מופעים חדשים ב-App Engine. יותר מ-max_pending_latency, ‏ App Engine ינסה ליצור מופע חדש. בין השעה שצוינה על ידי min_pending_latency לבין השעה שצוינה על ידי max_pending_latency, מערכת App Engine תנסה לעשות שימוש חוזר במופע קיים. אם אף מופע לא יכול לעבד את הבקשה לפני max_pending_latency,‏ App Engine ייצור מופע חדש. דוגמה automatic_scaling: target_cpu_utilization: 0.65 min_instances: 5 max_instances: 100 min_pending_latency: 30ms max_pending_latency: automatic max_concurrent_requests: 50
basic_scaling	באפליקציות שמשתמשות בסוג המופע B1 ומעלה, צריך לציין את הרכיב הזה או את הרכיב manual_scaling. הרכיב הזה מאפשר שינוי גודל בסיסי של סוגי מופעים B1 ומעלה, יכול להכיל את הרכיבים הבאים: max_instances שדה חובה. מספר המכונות המקסימלי ש-App Engine יכול ליצור לגרסת השירות הזו. כדאי להשתמש בזה כדי להגביל את העלויות של שירות. idle_timeout אופציונלי. המופע יושבת אחרי פרק הזמן הזה, אחרי קבלת הבקשה האחרונה שלו. ערך ברירת המחדל הוא 5 דקות (5m). דוגמה basic_scaling: max_instances: 11 idle_timeout: 10m
manual_scaling	באפליקציות שמשתמשות בסוג המופע B1 ומעלה, צריך לציין את הרכיב הזה או את הרכיב basic_scaling. הרכיב הזה מאפשר לשנות את הגודל של מחלקות מופעים B1 ומעלה באופן ידני, והוא יכול להכיל את הרכיב הבא: instances מספר המופעים להקצאה לשירות בהתחלה. דוגמה manual_scaling: instances: 5