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

הדף הזה רלוונטי ל-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, אז חיבורי היעד מוגדרים לשימוש במנהרה שצוינה. אם היעד משתמש ב-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) גדול יותר מגודל שטח האחסון הזמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה לערך `true`. כשמשתמשים ב-`true`, המערכת לא קוראת את מטען הייעודי (payload) של בקשת HTTP לתוך מאגר זמני, אלא מעבירה אותו כמו שהוא לנקודת הקצה של היעד. במקרה כזה, המערכת תדלג על כל המדיניות שפועלת על מטען הייעודי (payload) בתהליך הבקשה `TargetEndpoint`. ראו גם בקשות ותגובות בסטרימינג.
`response.streaming.enabled`	FALSE	כברירת מחדל (false), נתוני ה-payload של תגובת HTTP נקראים לתוך מאגר זמני, והמדיניות שיכולה לפעול על ה-payload פועלת כמצופה. במקרים שבהם מטען ייעודי (payload) גדול יותר מגודל שטח האחסון הזמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה כ-TRUE. אם הערך הוא true, מטען הייעודי (payload) של תגובת ה-HTTP לא נקרא לתוך מאגר נתונים זמני; הוא מועבר כמו שהוא לזרימת התגובה `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`), מטען ייעודי (payload) של בקשת HTTP נקרא לתוך מאגר, והמדיניות שיכולה לפעול על המטען הייעודי פועלת כמצופה. במקרים שבהם מטען הייעודי (payload) גדול יותר מגודל שטח האחסון הזמני (10MB ב-Apigee), אפשר להגדיר את המאפיין הזה לערך `true`. כשמשתמשים ב-`true`, המטענים הייעודיים (payloads) של בקשות HTTP לא נקראים לתוך מאגר נתונים זמני, אלא מועברים כמו שהם לזרימת הבקשות של `TargetEndpoint`. במקרה כזה, המערכת תדלג על כל כללי המדיניות שפועלים על מטען הייעודי (payload) בתהליך הבקשה `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) גדול יותר מגודל שטח האחסון הזמני (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`	לא רלוונטי	הגדרת הזמן הקצוב לתפוגה של כל פרוקסי 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:

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

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

אם הערך קטן מאפס, המשמעות היא שחלף הזמן המקסימלי לטיפול בבקשה, ומעבד ההודעות מחזיר 504 Gateway Timeout.
הערך של io.timeout.millis מציין את משך הזמן המקסימלי שנקודת הקצה של היעד צריכה להגיב.

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

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