מסמך עזר בנושא מאפיינים של נקודות קצה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

במאמר הזה מתוארים מאפייני התעבורה שאפשר להגדיר בקובצי ההגדרות TargetEndpoint ו-ProxyEndpoint כדי לשלוט בהתנהגות של העברת ההודעות והחיבורים. מידע מקיף על אפשרויות ההגדרה של TargetEndpoint ו-ProxyEndpoint זמין במאמר חומר עזר בנושא הגדרת proxy ל-API.

מאפייני התעבורה של TargetEndpoint

רכיב HTTPTargetConnection בהגדרות TargetEndpoint מגדיר קבוצה של מאפייני העברה של HTTP. אפשר להשתמש במאפיינים האלה כדי להגדיר הגדרות ברמת התעבורה.

המאפיינים מוגדרים ברכיבי TargetEndpoint HTTPTargetConnection, כמו שמוצג בדוגמה הזו של מערך הגדרות אישיות:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <Properties>
      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
  </HTTPTargetConnection>
</TargetEndpoint>

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

מפרט של מאפיין התעבורה TargetEndpoint

שם המאפיין	ערך ברירת המחדל	תיאור
allow.post.without.content.length	FALSE	מאפשר לשלוח בקשות POST ללא תוכן בגוף הבקשה.
allow.put.without.content.length	FALSE	מאפשר לשלוח בקשות PUT ללא תוכן בגוף הבקשה.
allow.tls.session.resumption	TRUE	אם true (ברירת המחדל) הלקוחות משתמשים מחדש בסשנים של TLS כשהם יוצרים חיבורים חדשים ליעד. מגדירים את הערך false אם לא רוצים לעשות שימוש חוזר בסשן TLS. שימוש חוזר בסשן בדרך כלל מקצר את זמני החיבור, אבל יכול להיות שיעדים מסוימים לא יתמכו בשימוש חוזר בסשן או יתקשו בכך.
keepalive.timeout.millis	60000	הזמן הקצוב לתפוגה של חוסר פעילות בחיבור היעד במאגר החיבורים. אם החיבור במאגר לא פעיל מעבר למגבלה שצוינה, החיבור ייסגר.
connect.timeout.millis	3000	זמן קצוב לתפוגה של חיבור ליעד. אם מתרחש זמן קצוב לתפוגה של חיבור, Apigee מחזיר קוד סטטוס HTTP‏ 503. במקרים מסוימים, יכול להיות שיוחזר קוד סטטוס HTTP‏ 504 כשמשתמשים ב-LoadBalancer בהגדרת TargetServer ומתרחש זמן קצוב לתפוגה. הערה: במקרים מסוימים, מערכת Apigee תנסה להתחבר מחדש באופן אוטומטי עד שלוש פעמים. כתוצאה מכך, יכול להיות שמשך הניסיון החוזר הכולל יהיה ארוך יותר ממה שהוגדר עבור connect.timeout.millis.
ignore.allow.header.for.405	TRUE	מאפשר להעביר את קוד הסטטוס 405 בחזרה ללקוח. אם מפעילים את הדגל, Apigee מחזיר 405 במקום קוד הסטטוס 502.
io.timeout.millis	55000	אם אין נתונים לקריאה למשך מספר אלפיות השנייה שצוין, או אם השקע לא מוכן לכתיבת נתונים למשך מספר אלפיות השנייה שצוין, הטרנזקציה נחשבת כזמן קצוב לתפוגה. אם מתרחש פסק זמן במהלך קריאת בקשת ה-HTTP מ-ingress, מוחזרת השגיאה 408 Request Timeout. הפונקציה 408 Request Timeout לא תוחזר אם יתרחש זמן קצוב לתפוגה בזמן כתיבת בקשה ליעד. אם מתרחש זמן קצוב לתפוגה במהלך כתיבת בקשת ה-HTTP או קריאת תגובת ה-HTTP, מוחזרת השגיאה 504 Gateway Timeout. מידע נוסף זמין במאמר בנושא הגדרה של io.timeout.millis ו-api.timeout.
supports.http11	TRUE	אם זה true והלקוח שולח בקשת 1.1, בקשת 1.1 נשלחת גם ליעד, אחרת בקשת 1.0 נשלחת ליעד.
use.proxy	TRUE	אם קובץ ההחלפה של Apigee hybrid מכיל את ההגדרה HTTP_PROXY, כמו שמתואר במאמר הגדרת העברת בקשות דרך שרת proxy עבור שרתי proxy של API, צריך להשתמש במאפיין הזה כדי לנהל או לשלוט בשרתי ה-proxy שלא אמורים להשתמש בהגדרת ה-proxy. אם הערך הוא false, שרת ה-Proxy של ה-API ידלג על הגדרות ה-Proxy ל-HTTP שצוינו בקובץ ההחלפות של Apigee Hybrid לחיבורים ליעד שהוגדרו ב-Proxy.
use.proxy.tunneling	TRUE	אם ההגדרה הזו היא true, והגדרות ה-proxy מצוינות בקובץ של Apigee hybrid, כמו שמתואר במאמר הגדרת העברת בקשות דרך שרת proxy ל-API proxies, אז חיבורי היעד מוגדרים לשימוש במנהרה שצוינה. אם היעד משתמש ב-TLS/SSL, המערכת מתעלמת מהמאפיין הזה וההודעה תמיד נשלחת באמצעות מנהרה.
use.proxy.host.header.with.target.uri	TRUE	הגדרת המארח והיציאה של היעד ככותרת Host. כברירת מחדל, המארח והיציאה של ה-proxy מוגדרים ככותרות Host. אפשר להגדיר את המאפיין הזה רק בנקודת הקצה של היעד. לדוגמה: <HTTPTargetConnection> <Properties> <Property name="use.proxy.host.header.with.target.uri">true</Property> </Properties> <URL>https://mocktarget.apigee.net/my-target</URL> </HTTPTargetConnection>
response.payload. parse.limit	10M	כברירת מחדל (10M). משתמשים במאפיין response.payload.parse.limit כדי להגדיר את הגודל המקסימלי של מטען הייעודי (payload) שאפשר לעבד בתהליך התגובה, במגה-בייט (M). המגבלה המינימלית שאפשר להגדיר היא 10M והמגבלה המקסימלית שאפשר להגדיר היא 30M. אם הנכס לא מוגדר, מגבלת ברירת המחדל היא 10 מיליון. מידע נוסף זמין במאמר בנושא גודל מטען ייעודי (payload) של הודעה.
request.streaming.enabled	FALSE	כברירת מחדל (false), נתוני ה-payload של בקשות HTTP נקראים לתוך מאגר נתונים זמני, והמדיניות שיכולה לפעול על ה-payload פועלת כמצופה. במקרים שבהם נתוני ה-payload גדולים יותר מגודל שטח האחסון הזמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה לערך true. כשהערך הוא true, נתוני ה-payload של בקשות HTTP לא נקראים לתוך מאגר נתונים זמני, אלא מועברים בסטרימינג כמו שהם לנקודת היעד. במקרה כזה, כל כללי המדיניות שפועלים על ה-payload בתהליך הבקשה TargetEndpoint נדלגים. אפשר לעיין גם במאמר העברת בקשות ותגובות בסטרימינג.
response.streaming.enabled	FALSE	כברירת מחדל (false), נתוני ה-payload של תגובת ה-HTTP נקראים לתוך מאגר זמני, והמדיניות שיכולה לפעול על ה-payload פועלת כמצופה. במקרים שבהם מטען הייעודי (payload) גדול יותר מגודל שטח אחסון זמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה כ-true. אם הערך הוא true, מטען הייעוד (payload) של תגובת ה-HTTP לא נקרא לתוך מאגר זמני (buffer), אלא מועבר כמו שהוא לזרימת התגובה ProxyEndpoint. במקרה כזה, כללי המדיניות שפועלים על מטען הייעודי (payload) בתהליך התגובה TargetEndpoint נדחקים הצידה. ראו גם בקשות ותגובות של סטרימינג.
success.codes	לא רלוונטי	כברירת מחדל, Apigee מתייחסת לקוד HTTP‏ 4XX או 5XX כשגיאות, ולקוד HTTP‏ 1XX, 2XX, 3XX כהצלחה. המאפיין הזה מאפשר הגדרה מפורשת של קודי הצלחה. לדוגמה, 2XX, 1XX, 505 מתייחס לכל קודי תגובת HTTP‏ 100, 200 ו-505 כאל הצלחה. הגדרת המאפיין הזה מחליפה את ערכי ברירת המחדל. לכן, אם רוצים להוסיף את קוד ה-HTTP‏ 400 לרשימת קודי ההצלחה שמוגדרים כברירת מחדל, צריך להגדיר את המאפיין הזה כך: <Property name="success.codes">1xx,2xx,3xx,400</Property> אם רוצים שרק קוד HTTP‏ 400 ייחשב כקוד הצלחה, צריך להגדיר את המאפיין כך: <Property name="success.codes">400</Property> אם מגדירים את קוד ה-HTTP‏ 400 כקוד ההצלחה היחיד, הקודים 1xx, 2xx ו-3xx נחשבים כקודים של שגיאות.
compression.algorithm	לא רלוונטי	כברירת מחדל, Apigee מכבד את סוג הדחיסה שהוגדר (gzip, ‏ deflate או none) להודעות שהתקבלו. אם הבקשה מתקבלת מהלקוח באמצעות דחיסה, למשל gzip,‏ Apigee מעביר את הבקשה ליעד באמצעות דחיסת gzip. אם התשובה שמתקבלת מהיעד משתמשת ב-deflate, ‏ Apigee מעביר את התשובה ללקוח באמצעות deflate. הערכים הנתמכים הם: ‫gzip: שליחת ההודעה תמיד תתבצע באמצעות דחיסת gzip ‫deflate: שליחת ההודעה תמיד תתבצע באמצעות דחיסת deflate none: ההודעה תמיד תישלח ללא דחיסה מידע נוסף: האם Apigee תומך בדחיסה/ביטול דחיסה באמצעות דחיסת GZIP/deflate?
request.retain.headers. enabled	TRUE	כברירת מחדל, Apigee תמיד שומרת את כל כותרות ה-HTTP בהודעות יוצאות. אם הערך מוגדר כ-true, כל כותרות ה-HTTP שמופיעות בבקשה הנכנסת מוגדרות בבקשה היוצאת.
request.retain.headers	לא רלוונטי	המאפיין הזה מגדיר כותרות HTTP ספציפיות מהבקשה שצריך להגדיר בבקשה היוצאת לשירות היעד. לדוגמה, כדי להעביר את הכותרת User-Agent, צריך להגדיר את הערך של request.retain.headers ל-User-Agent. אפשר לציין כמה כותרות HTTP ברשימה שמופרדת באמצעות פסיקים, למשל User-Agent,Referer,Accept-Language. המאפיין הזה מבטל את המאפיין request.retain.headers.enabled. אם המאפיין request.retain.headers.enabled מוגדר ל-false, כל הכותרות שצוינו במאפיין request.retain.headers עדיין מוגדרות בהודעה היוצאת.
response.retain.headers. enabled	TRUE	כברירת מחדל, Apigee תמיד שומרת את כל כותרות ה-HTTP בהודעות יוצאות. אם הערך הוא true, כל כותרות ה-HTTP שמופיעות בתגובה הנכנסת משירות היעד מוגדרות בתגובה היוצאת לפני שהיא מועברת אל ProxyEndpoint.
response.retain.headers	לא רלוונטי	המאפיין הזה מגדיר כותרות HTTP ספציפיות מהתגובה שצריך להגדיר בתגובה היוצאת לפני שהיא מועברת אל ProxyEndpoint. לדוגמה, כדי להעביר את הכותרת Expires, צריך להגדיר את הערך של response.retain.headers כ-Expires. אפשר לציין כמה כותרות HTTP כרשימה מופרדת בפסיקים, לדוגמה, Expires,Set-Cookie. המאפיין הזה מבטל את ההגדרה של response.retain.headers.enabled. אם response.retain.headers.enabled מוגדר כ-false, הכותרות שצוינו במאפיין response.retain.headers עדיין מוגדרות בהודעה היוצאת.
retain.queryparams. enabled	TRUE	כברירת מחדל, Apigee תמיד שומר את כל הפרמטרים של השאילתה בבקשות יוצאות. כשמגדירים את הערך true, כל פרמטרים של שאילתה שמופיעים בבקשה הנכנסת מוגדרים בבקשה היוצאת לשירות היעד.
retain.queryparams	לא רלוונטי	המאפיין הזה מגדיר פרמטרים ספציפיים של שאילתה שיוגדרו בבקשה היוצאת. לדוגמה, כדי לכלול את פרמטר השאילתה apikey מהודעת הבקשה, מגדירים את retain.queryparams לערך apikey. אפשר לציין כמה פרמטרים של שאילתה כרשימה מופרדת בפסיקים, לדוגמה, apikey,environment. המאפיין הזה מבטל את ההגדרה של retain.queryparams.enabled.

מאפייני התעבורה של ProxyEndpoint

רכיבי ProxyEndpoint HTTPTargetConnection מגדירים קבוצה של מאפייני העברה של HTTP. אפשר להשתמש במאפיינים האלה כדי להגדיר הגדרות ברמת התעבורה.

המאפיינים מוגדרים ברכיבי ProxyEndpoint HTTPProxyConnection, כמו שמוצג בדוגמה הזו של מערך הגדרות אישיות:

<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <Properties>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
  </HTTPProxyConnection>
</ProxyEndpoint>

כותרות של בקשות

בקשת HTTP נכנסת כוללת את כותרות ה-HTTP שנשלחו על ידי הלקוח. אם לקוח שולח כותרות עם שמות שתואמים לתבנית X-Apigee-*, הן מוסרות מבקשות נכנסות. דפוס השם הזה שמור ל-Apigee.

מפרט של מאפיין Transport של ProxyEndpoint

שם המאפיין	ערך ברירת המחדל	תיאור
X-Forwarded-For	FALSE	אם המדיניות מוגדרת כ-True, כתובת ה-IP של המארח הווירטואלי מתווספת לבקשה היוצאת כערך של כותרת ה-HTTP‏ X-Forwarded-For.
request.streaming. enabled	false	כברירת מחדל (false), מטענים ייעודיים (payloads) של בקשות HTTP נקראים לתוך מאגר נתונים זמני, ומדיניות שיכולה לפעול על המטען הייעודי פועלת כמצופה. במקרים שבהם המטענים הייעודיים גדולים יותר מגודל שטח האחסון הזמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה ל-true. כשהערך הוא true, מטענים ייעודיים של בקשות HTTP לא נקראים לתוך מאגר נתונים זמני, אלא מועברים כפי שהם לזרימת הבקשות TargetEndpoint. במקרה כזה, כל מדיניות שפועלת על המטען הייעודי בזרימת הבקשות ProxyEndpoint נדחית. אפשר לעיין גם במאמר העברת בקשות ותגובות בסטרימינג.
request.payload. parse.limit	10M	כברירת מחדל (10M). משתמשים במאפיין request.payload.parse.limit כדי להגדיר את גודל המטען הייעודי (payload) המקסימלי שאפשר לעבד בתהליך הבקשה, במגה-בייט (M). המגבלה המינימלית שאפשר להגדיר היא 10M והמגבלה המקסימלית שאפשר להגדיר היא 30M. אם הנכס לא מוגדר, מגבלת ברירת המחדל היא 10 מיליון. מידע נוסף זמין במאמר בנושא גודל מטען ייעודי (payload) של הודעה.
response.streaming. enabled	false	כברירת מחדל (false), נתוני ה-payload של תגובת ה-HTTP נקראים לתוך מאגר, ומדיניות שיכולה לפעול על ה-payload פועלת כמצופה. במקרים שבהם ה-payload גדול יותר מ<b>שטח האחסון הזמני</b> (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה ל-true. כשהערך הוא true, נתוני ה-payload של תגובת ה-HTTP לא נקראים לתוך מאגר, אלא מועברים בסטרימינג ללקוח כמו שהם. במקרה כזה, כל מדיניות שפועלת על ה-payload בזרימת התגובה ProxyEndpoint נדחית. אפשר לעיין גם במאמר בנושא בקשות ותגובות בסטרימינג.
compression.algorithm	לא רלוונטי	כברירת מחדל, Apigee מכבד את סוג הדחיסה שהוגדר (gzip, ‏ deflate או none) להודעות שמתקבלות. לדוגמה, אם לקוח שולח בקשה שמשתמשת בדחיסת gzip, ‏ Apigee מעביר את הבקשה ליעד באמצעות דחיסת gzip. אפשר להגדיר אלגוריתמים של דחיסה כך שיופעלו באופן מפורש על ידי הגדרת המאפיין הזה ב-TargetEndpoint או ב-ProxyEndpoint. הערכים הנתמכים הם: ‫gzip: שליחת ההודעה תמיד תתבצע באמצעות דחיסת gzip ‫deflate: שליחת ההודעה תמיד תתבצע באמצעות דחיסת deflate none: ההודעה תמיד תישלח ללא דחיסה מידע נוסף: האם Apigee תומך בדחיסה/ביטול דחיסה באמצעות דחיסת GZIP/deflate?
api.timeout	לא רלוונטי	הגדרת הזמן הקצוב לתפוגה של שרתי proxy ספציפיים ל-API (באלפיות שנייה) אפשר להגדיר שפרוקסי של API, גם כאלה שמופעל בהם סטרימינג, יפסיקו לפעול אחרי זמן מוגדר עם סטטוס 504 Gateway Timeout. חשוב: ערך הזמן הקצוב לתפוגה שצוין צריך להיות קצר יותר מהזמן הקצוב לתפוגה הרגיל של מעבד ההודעות, שהוא 300 שניות. לדוגמה, כדי להגדיר שפרוקסי יפסיק לפעול אחרי 180,000 אלפיות השנייה (שלוש דקות), מוסיפים את המאפיין הבא ל-HTTPProxyConnection: <Property name="api.timeout">180000</Property> אי אפשר להגדיר את המאפיין הזה באמצעות משתנה. מידע נוסף זמין במאמר בנושא הגדרה של io.timeout.millis ו-api.timeout.
HTTPHeader.allowDuplicates	לא רלוונטי	ההגדרה הזו מאפשרת כותרות כפולות (לכותרות ספציפיות). <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection>
HTTPHeader.multiValued	לא רלוונטי	ההגדרה הזו מאפשרת כותרות כפולות (לכותרות ספציפיות). <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection>

הגדרת io.timeout.millis ו-api.timeout

הפעולות של io.timeout.millis ו-api.timeout קשורות זו לזו. בכל בקשה ל-proxy ל-API:

1. ה-Ingress (שנקרא גם מאזן עומסים פנימי) שולח את ערך הזמן הקצוב לתפוגה שלו למעבד ההודעות. ערך הזמן הקצוב לתפוגה הזה מוגדר כברירת מחדל ל-300 שניות, ואי אפשר להגדיר אותו.
2. לאחר מכן, מעבד ההודעות מגדיר את api.timeout:
   1. אם api.timeout לא מוגדר ברמת ה-proxy, צריך להשתמש בערך הזמן הקצוב לתפוגה שמוגדר על ידי Ingress.
   2. אם הערך של api.timeout מוגדר ברמת ה-proxy, צריך להגדיר אותו ב-Message Processor לערך הנמוך מבין ערך הזמן הקצוב לתפוגה של Ingress או הערך של api.timeout.

3. הערך של api.timeout מציין את משך הזמן המקסימלי שמוקצב ל-proxy ל-API לביצוע הפעולה, מבקשת ה-API ועד לתשובה.

   אחרי שכל מדיניות ב-proxy ל-API מופעלת, או לפני שמעבד בקשות שולח את הבקשה לנקודת קצה היעד, מעבד בקשות מחשב (api.timeout – הזמן שחלף מתחילת הבקשה).

   אם הערך קטן מאפס, המשמעות היא שחלף הזמן המקסימלי לטיפול בבקשה, ומעבד ההודעות מחזיר 504 Gateway Timeout.

4. הערך של io.timeout.millis מציין את משך הזמן המקסימלי שנקודת הקצה של היעד צריכה להגיב.

   לפני שמתחברים לנקודת קצה של יעד, מעבד ההודעות קובע את הערך הקטן מבין שני הערכים הבאים: (api.timeout – הזמן שחלף מתחילת הבקשה) ו-io.timeout.millis. לאחר מכן, המערכת מגדירה את הערך הזה ל-io.timeout.millis.

   אם מתרחש זמן קצוב לתפוגה במהלך כתיבת בקשת ה-HTTP או קריאת תגובת ה-HTTP, מוחזרת השגיאה 504 Gateway Timeout.