מאמר עזרה בנושא קובץ 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. קובץ התצורה חייב לכלול לפחות רשומה אחת של runtime.

לכל שירות באפליקציה יש קובץ app.yaml משלו, שמשמש כמתאר לפריסה שלו. כדי ליצור ולפרוס קובצי app.yaml לשירותים נוספים באפליקציה, קודם צריך ליצור את הקובץ app.yaml לשירות default. למידע נוסף על בניית שירותים מרובים באפליקציה, ראו בניית שירותי אינטרנט ב-App Engine.

תחביר

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

פורמט YAML תומך בהערות. המערכת מתעלמת משורה שמתחילה בתו סולמית (#):

# This is a comment.

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

דוגמה

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

runtime: python315

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	זה שינוי אופציונלי. אם אתם משתמשים בסביבת זמן ריצה שתומכת ב-buildpacks, אתם יכולים להגדיר משתני סביבת build בקובץ app.yaml. מידע נוסף זמין במאמר שימוש במשתני סביבה של build.
default_expiration	זה שינוי אופציונלי. מגדירה תקופת ברירת מחדל גלובלית לשמירה במטמון לכל ה-handlers של קבצים סטטיים באפליקציה. אפשר גם להגדיר משך זמן לשמירה במטמון של רכיבי handler ספציפיים של קבצים סטטיים. הערך הוא מחרוזת של מספרים ויחידות, שמופרדים ברווחים. היחידות יכולות להיות d לימים, h לשעות, m לדקות ו-s לשניות. לדוגמה, "4d 5h" מגדיר את תפוגת המטמון ל-4 ימים ו-5 שעות אחרי הבקשה הראשונה לקובץ. אם לא מציינים ערך, שרת הייצור מגדיר את התפוגה ל-10 דקות. דוגמה ב-Python: runtime: python315 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 ‫ הפעלת בקשות warmup. הגדרת בקשות warmup לדוגמה: inbound_services: - warmup
instance_class	זה שינוי אופציונלי. מחלקת המכונה של השירות הזה. הערכים הבאים זמינים בהתאם לשינוי קנה המידה של השירות: התאמה אוטומטית לעומס (automatic scaling) F1, F2, F4, F4_1G ברירת מחדל: F1 אפשר להשתמש ברכיב automatic_scaling כדי לשנות את הגדרות ברירת המחדל של התאמה אוטומטית לעומס (automatic scaling), כמו מספר המכונות המינימלי והמקסימלי, זמן האחזור והחיבורים בו-זמנית. הערה: אם הערך של instance_class הוא F2 או יותר, אפשר לשפר את המכונות על ידי הגדרת הערך של max_concurrent_requests לערך גבוה יותר מערך ברירת המחדל 10. כדי לקבוע את הערך האופטימלי, מגדילים אותו בהדרגה ועוקבים אחרי הביצועים של האפליקציה. התאמה בסיסית וידנית לעומס B1, B2, B4, B4_1G, B8 ברירת מחדל: B2 בסוגי מכונות בסיסיים וידניים צריך לציין את הרכיב basic_scaling או את הרכיב manual_scaling.
runtime	חובה. השם של סביבת זמן הריצה שבה משתמשת האפליקציה. לדוגמה, כדי לציין את סביבת זמן הריצה, משתמשים ב: runtime: python315
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].
vpc_access	זה שינוי אופציונלי. מגדירים Direct VPC egress לשירות, כדי שהאפליקציה תוכל לשלוח בקשות למשאבים פנימיים ברשת ה-VPC. ההגדרה הזו כוללת את השדות הבאים: network_interface חובה לציין את השדה הזה כשמציינים את השדה vpc_access. מכיל הגדרות של ממשק הרשת לשימוש בתעבורת נתונים יוצאת (egress) ישירה של VPC. אפשר לציין את network, את subnet או את שניהם. אם מציינים רק את network, הערך של subnet יהיה זהה לזה של network כברירת מחדל. network השם של רשת ה-VPC שבה משתמשים ל-Direct VPC egress. ב-VPC משותף, אפשר לציין את נתיב המשאב המלא. subnet השם של רשת המשנה של ה-VPC שבה משתמשים לתעבורת נתונים יוצאת (egress) ישירה של VPC. ב-VPC משותף, אפשר לציין את נתיב המשאב המלא. tags אופציונלי. רשימה של תגי רשת שצריך לשייך למכונות של השירות, לשימוש בכללי חומת אש ובמדיניות ניתוב. vpc_egress אופציונלי. ההגדרה הזו קובעת איך תנותב תנועה יוצאת. בשדה הזה אפשר להגדיר את ההגדרות הבאות: private-ranges-only ברירת מחדל. רק תעבורת נתונים לכתובות IP פנימיות מנותבת דרך רשת ה-VPC. תעבורת הנתונים באינטרנט משתמשת בנתיב ברירת המחדל של App Engine. all-traffic כל הבקשות היוצאות מנותבות דרך רשת ה-VPC. במאמרים התחברות לרשת VPC באמצעות Direct VPC egress ומכסות ומגבלות מוסבר איך מגדירים 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	זה שינוי אופציונלי. משך הזמן שבו קובץ סטטי שמוצג על ידי ה-handler הזה צריך להישמר במטמון על ידי שרתי proxy ודפדפנים. הערך הוא מחרוזת של מספרים ויחידות, שמופרדים ברווחים. היחידות יכולות להיות d לימים, h לשעות, m לדקות ו-s לשניות. לדוגמה, "4d 5h" מגדיר את תפוגת המטמון ל-4 ימים ו-5 שעות אחרי הבקשה הראשונה לקובץ. אם לא מציינים את המאפיין, המערכת משתמשת ב-default_expiration של האפליקציה. פרטים נוספים זמינים במאמר בנושא תפוגת תוקף של מטמון.
http_headers	זה שינוי אופציונלי. אתם יכולים להגדיר כותרות HTTP לתגובות של ה-handlers של הקבצים הסטטיים או של הספרייה. אם אתם צריכים להגדיר כותרות HTTP ב-handlers של 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 handler דורש שהמשתמש יהיה מחובר לחשבון. לרכיב הזה יש שלושה ערכים אפשריים: optional ברירת מחדל. לא מחייב שהמשתמש יהיה מחובר לחשבון. required אם המשתמש נכנס לחשבון, ה-handler ממשיך כרגיל. אחרת, תתבצע הפעולה שצוינה ב-auth_fail_action. admin כמו ב-required, הפעולה auth_fail_action מתבצעת אם המשתמש לא מחובר לחשבון. בנוסף, אם המשתמש הוא לא אדמין באפליקציה, תוצג לו הודעת שגיאה בלי קשר להגדרה של auth_fail_action. אם המשתמש הוא אדמין, ה-handler ממשיך. כש-URL handler עם הגדרת login שונה מ-optional תואם לכתובת URL, ה-handler בודק קודם אם המשתמש נכנס לאפליקציה באמצעות אפשרות האימות שלה. אם לא, כברירת מחדל המשתמש מופנה לדף הכניסה. אפשר גם להשתמש ב-auth_fail_action כדי להגדיר את האפליקציה כך שפשוט תדחה בקשות ל-handler ממשתמשים שלא אומתו כראוי, במקום להפנות את המשתמש לדף הכניסה. הערה: הגבלת ההתחברות של admin מתקיימת גם לבקשות פנימיות שבהן App Engine מגדיר כותרות מיוחדות מתאימות של X-Appengine. לדוגמה, משימות מתוזמנות של cron עומדות בהגבלה admin, כי App Engine מגדיר כותרת HTTP‏ X-Appengine-Cron: true בבקשות המתאימות. עם זאת, הבקשות לא יעמדו בהגבלת ההתחברות של required, כי משימות מתוזמנות של cron לא מופעלות על ידי משתמש.
mime_type	זה שינוי אופציונלי. אם מציינים סוג MIME, כל הקבצים שמוצגים על ידי ה-handler הזה יוצגו באמצעות סוג ה-MIME שצוין. אם לא מציינים סוג MIME, הוא ייקבע לפי הסיומת של שם הקובץ. אם אותו קובץ מועלה עם כמה סיומות, הסיומת שתתקבל יכולה להיות תלויה בסדר שבו ההעלאות התרחשו. מידע נוסף על סוגי המדיה האפשריים של MIME זמין באתר סוגי המדיה של IANA MIME.
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	זה שינוי אופציונלי. מציין שבקשות ל-handler הספציפי צריכות לטרגט את האפליקציה. הערך היחיד שאפשר להזין ברכיב script הוא auto, כי כל התנועה מועברת באמצעות הפקודה entrypoint. כדי להשתמש ב-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 עם אותו נתיב. הפרמטרים של השאילתה נשמרים בהפניה לכתובת URL אחרת. דוגמה ב-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 הזה יפנה אליהם. הפעולה הזו נדרשת כי ה-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 כדי למפות קבצים ספציפיים במבנה של ספרייה בלי למפות את כל הספרייה.

רכיבי התאמה לעומס (scaling)

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

למידע נוסף על התאמה לעומס (scaling) של אפליקציות ב-App Engine, קראו את המאמר סוגי התאמה לעומס.

רכיב	תיאור
automatic_scaling	זה שינוי אופציונלי. רלוונטי רק לאפליקציות שמשתמשות במחלקה של מכונה מסוג F1 ומעלה. מציינים את הרכיב הזה כדי לשנות את הגדרות ברירת המחדל להתאמה אוטומטית לעומס (automatic scaling), כמו הגדרת רמות מינימום ומקסימום למספר המכונות, זמן האחזור והחיבורים בו-זמנית לשירות. הרכיב הזה יכול להכיל את הרכיבים הבאים: max_instances אופציונלי. צריך לציין ערך בין 0 ל-2147483647, כאשר אפס משבית את ההגדרה. הערה: החל ממרץ 2025, באפליקציות חדשות, App Engine מגדיר את ברירת המחדל של מספר המכונות המקסימלי לפריסות בסביבה הרגילה ל-20. השינוי הזה לא משפיע על בקשות קיימות. כדי לשנות את ברירת המחדל, צריך לציין ערך חדש בין 0 ל-2147483647, ולפרוס גרסה חדשה או לפרוס מחדש מעל גרסה קיימת. כדי להשבית את הגדרת ברירת המחדל של מספר המכונות המקסימלי, מציינים את הערך המקסימלי המותר 2147483647. בגרסאות שמוגדרות עם vpc_access, ההגדרה max_instances לא יכולה לחרוג ממכסת המכונות של Direct VPC בפרויקט, שהיא 100 כברירת מחדל. אם מציינים את הערך 0 או משמיטים את max_instances, המערכת של App Engine מחילה מגבלת ברירת מחדל, כמו שמתואר במאמר מגבלות על תעבורת נתונים יוצאת ב-Direct VPC. הפרמטר הזה מציין את המספר המקסימלי של מכונות ש-App Engine יכול ליצור לגרסת המודול הזו. כדאי להשתמש בזה כדי להגביל את העלויות של מודול. min_instances אזהרה: כדי שהתכונה הזו תפעל כמו שצריך, צריך לוודא שבקשות warmup מופעלות ושהאפליקציה מטפלת בבקשות warmup. הערה: ההגדרה הזו רלוונטית רק אם גרסת האפליקציה שמוגדרת בקובץ app.yaml הזה מוגדרת לקבלת תנועה. למידע נוסף על ניתוב תנועה לגרסאות שונות של אפליקציה, ראו פיצול תנועה. אופציונלי. מספר המכונות המינימלי ש-App Engine ייצור לגרסת המודול הזו. המכונות האלה מטפלות בתנועה כשמגיעות בקשות, וממשיכות לטפל בתנועה גם כשמופעלות מכונות נוספות לפי הצורך כדי לטפל בתנועה. צריך לציין ערך בין 0 ל-1,000. אפשר להגדיר את הפרמטר לערך 0 כדי לאפשר התאמה ל-0 מכונות, וכך להוזיל את העלויות כשאין בקשות שמטופלות. חשוב לזכור שאתם מחויבים על מספר המכונות שציינתם, גם אם הן לא מקבלות תנועה. max_idle_instances זה שינוי אופציונלי. המספר המקסימלי של מכונות לא פעילות ש-App Engine צריך לשמור לגרסה הזו. צריך לציין ערך בין 1 ל-1,000. אם לא מציינים ערך, ערך ברירת המחדל הוא automatic, כלומר App Engine ינהל את מספר המכונות במצב המתנה. חשוב לזכור: ערך מקסימלי גבוה מפחית את מספר המכונות במצב חוסר פעילות באופן הדרגתי יותר, כשרמות העומס חוזרות למצב רגיל אחרי עלייה חדה. כך האפליקציה יכולה לשמור על ביצועים יציבים גם כשיש תנודות בעומס הבקשות, אבל גם מספר המכונות הלא פעילות (וכתוצאה מכך עלויות ההפעלה) עולה בתקופות של עומס כבד. אם מגדירים ערך מקסימלי נמוך, עלויות התפעול נמוכות יותר, אבל הביצועים עלולים להיפגע אם רמות העומס משתנות. הערה: כשחוזרים לרמות רגילות אחרי עלייה חדה בעומס, מספר המכונות במצב המתנה יכול לחרוג באופן זמני מהמספר המקסימלי שציינתם. עם זאת, לא תחויבו על יותר מופעים מהמספר המקסימלי שציינתם. min_idle_instances אזהרה: כדי שהתכונה הזו תפעל כמו שצריך, צריך לוודא שבקשות warmup מופעלות ושהאפליקציה מטפלת בבקשות warmup. הערה: ההגדרה הזו רלוונטית רק אם גרסת האפליקציה שמוגדרת בקובץ 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. הפרמטר הזה מציין את סף השימוש במעבד (CPU) שבו יופעלו מכונות חדשות כדי לטפל בתנועה. כך אפשר לאזן בין הביצועים לבין העלות: ערכים נמוכים יותר משפרים את הביצועים ומגדילים את העלות, וערכים גבוהים יותר מפחיתים את הביצועים אבל גם מפחיתים את העלות. לדוגמה, הערך 0.7 פירושו שמכונות חדשות יופעלו אחרי שהשימוש ב-CPU יגיע ל-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. הרכיב הזה מאפשר התאמה בסיסית לעומס (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