הפניה להגדרת proxy ל-API

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

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

אם אתם מפתחים שמשתמשים ב-Apigee, הפעולות העיקריות שלכם בפיתוח כוללות: הגדרת שרתי proxy ל-API שפועלים כשרתי proxy לממשקי API או לשירותי קצה עורפי. המסמך הזה הוא חומר עזר לכל רכיבי ההגדרה שזמינים לכם כשאתם יוצרים שרתי proxy של API.

אם אתם לומדים איך ליצור שרתי proxy ל-API, מומלץ להתחיל עם הנושא יצירת שרת proxy פשוט ל-API.

עורכים את ההגדרות של proxy ל-API באמצעות אחת מהשיטות הבאות:

משתמשים בממשק המשתמש או ב-API של Apigee.
מורידים את חבילת ההגדרות של proxy ל-API, עורכים אותה באופן ידני ומעלים את ההגדרה החדשה ל-Apigee, כמו שמתואר במאמר בנושא הורדה והעלאה של חבילת הגדרות של proxy ל-API.

מבנה ספריות של הגדרות proxy ל-API

מבנה הספריות של הגדרת proxy ל-API מוצג בהמשך:

מציג את מבנה הספרייה שבה apiproxy הוא שורש. ישירות מתחת לספרייה apiproxy נמצאות הספריות policies,‏ proxies,‏ resources ו-targets, וגם הקובץ weatherapi.xml.

הגדרת proxy ל-API מורכבת מהתוכן הבא:

הגדרת הבסיס	הגדרות התצורה העיקריות של proxy ל-API.
ProxyEndpoint	הגדרות לחיבור HTTP נכנס (מבקשות של אפליקציות אל Apigee), זרימות בקשות ותגובות וקבצים מצורפים של מדיניות.
TargetEndpoint	הגדרות לחיבור HTTP יוצא (מ-Apigee לשירות הקצה העורפי), זרימות של בקשות ותשובות וקבצים מצורפים של מדיניות.
Flows	צינורות בקשות ותגובות של ProxyEndpoint ו-TargetEndpoint שאפשר לצרף אליהם כללי מדיניות.
מדיניות	קובצי הגדרה בפורמט XML שתואמים לסכימות המדיניות של Apigee.
Resources	סקריפטים, קובצי JAR וקובצי XSLT שהמדיניות מפנה אליהם כדי להריץ לוגיקה בהתאמה אישית.

הגדרה בסיסית

`/apiproxy/weatherapi.xml`

ההגדרה הבסיסית של שרת proxy ל-API, שקובעת את השם של שרת ה-proxy ל-API. השם חייב להיות ייחודי בארגון.

הגדרה לדוגמה:

<APIProxy name="weatherapi">
</APIProxy>

רכיבי הגדרה בסיסיים

שם	תיאור	ברירת מחדל	חובה?
`APIProxy`
`name`	השם של proxy ל-API, שחייב להיות ייחודי בארגון. התווים שמותר להשתמש בהם בשם מוגבלים לאלה: `A-Za-z0-9_-`	לא רלוונטי	כן
`revision`	מספר הגרסה של הגדרת proxy ל-API. אין צורך להגדיר במפורש את מספר הגרסה, כי Apigee עוקב באופן אוטומטי אחרי הגרסה הנוכחית של שרת ה-API הפרוקסי.	לא רלוונטי	לא
`ConfigurationVersion`	הגרסה של סכימת ההגדרות של שרת ה-proxy ל-API שאליה שרת ה-proxy הזה תואם. הערך הנתמך היחיד כרגע הוא majorVersion 4 ו-minorVersion 0. יכול להיות שנשתמש בהגדרה הזו בעתיד כדי לאפשר שינויים בפורמט של proxy ל-API.	4.0	לא
`Description`	תיאור טקסטואלי של ה-proxy ל-API. אם תספקו תיאור, הוא יוצג בממשק המשתמש של Apigee.	לא רלוונטי	לא
`DisplayName`	שם ידידותי למשתמש שעשוי להיות שונה מהמאפיין `name` של הגדרת proxy ל-API.	לא רלוונטי	לא
`Policies`	רשימה של כללי מדיניות בספרייה `/policies` של proxy ל-API הזה. בדרך כלל, הרכיב הזה מוצג רק כששרת ה-proxy ל-API נוצר באמצעות ממשק המשתמש של Apigee. זו פשוט הגדרה של מניפסט, שנועדה לספק שקיפות לגבי התוכן של proxy ל-API.	לא רלוונטי	לא
`ProxyEndpoints`	רשימה של נקודות קצה של שרת proxy בספרייה `/proxies` של proxy ה-API הזה. בדרך כלל רואים את הרכיב הזה רק כש-proxy ל-API נוצר באמצעות ממשק המשתמש של Apigee. זוהי פשוט הגדרה של מניפסט, שנועדה לספק שקיפות לגבי התוכן של proxy ל-API.	לא רלוונטי	לא
`Resources`	רשימת משאבים (JavaScript, ‏ Python, ‏ Java, ‏ XSLT) בספרייה `/resources` של ה-proxy ל-API הזה. בדרך כלל רואים את הרכיב הזה רק כש-proxy ל-API נוצר באמצעות ממשק המשתמש של Apigee. זו פשוט הגדרה של מניפסט, שנועדה לספק תצוגה של התוכן של proxy ל-API.	לא רלוונטי	לא
`Spec`	מזהה את מפרט OpenAPI שמשויך לשרת ה-proxy ל-API. הערך מוגדר ככתובת URL או כנתיב בחנות המפרטים.	לא רלוונטי	לא
`TargetServers`	רשימה של שרתי יעד שאליהם יש הפניה בנקודות קצה של יעד ב-proxy ל-API הזה. בדרך כלל רואים את הרכיב הזה רק כש-proxy ל-API נוצר באמצעות Apigee. זו פשוט הגדרה של מניפסט, שנועדה לספק שקיפות לגבי התוכן של proxy ל-API.	לא רלוונטי	לא
`TargetEndpoints`	רשימה של נקודות קצה לטירגוט בספרייה `/targets` של ה-proxy ל-API הזה. בדרך כלל רואים את הרכיב הזה רק כש-proxy ל-API נוצר באמצעות ממשק המשתמש של Apigee. זוהי פשוט הגדרה של מניפסט, שנועדה לספק שקיפות לגבי התוכן של proxy ל-API.	לא רלוונטי	לא

ProxyEndpoint

התמונה הבאה מציגה את זרימת הבקשה והתגובה:

הדגמה של לקוח שמתקשר לשירות HTTP. הבקשה עוברת דרך נקודת הקצה של ה-proxy ואז דרך נקודת הקצה של היעד, לפני שהיא מעובדת על ידי שירות ה-HTTP. התגובה עוברת דרך נקודת הקצה של היעד ואז דרך נקודת הקצה של ה-Proxy לפני שהיא מוחזרת ללקוח.

`/apiproxy/proxies/default.xml`

ההגדרה של ProxyEndpoint מגדירה את הממשק הנכנס (שפונה ללקוח) של שרת proxy ל-API. כשמגדירים נקודת קצה של שרת Proxy, מגדירים את תצורת הרשת שמגדירה איך אפליקציות לקוח (אפליקציות) צריכות להפעיל את ה-API שמועבר דרך ה-Proxy.

הגדרת ProxyEndpoint לדוגמה הבאה תישמר בתיקייה /apiproxy/proxies:

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

רכיבי ההגדרה הנדרשים בנקודת קצה בסיסית של שרת Proxy הם:

רכיבי ההגדרה של ProxyEndpoint

שם תיאור ברירת מחדל חובה?

ProxyEndpoint

name השם של נקודת הקצה של ה-proxy. חייב להיות ייחודי בהגדרת proxy ל-API, אם (במקרים נדירים) מוגדרים כמה נקודות קצה של proxy. התווים שמותרים בשם הם: A-Za-z0-9._\-$ %. לא רלוונטי כן

PreFlow ההגדרה הזו מגדירה את כללי המדיניות בזרימת PreFlow של בקשה או תגובה. לא רלוונטי כן

Flows

המאפיין מגדיר את המדיניות בזרימות מותנות של בקשה או תגובה.

לא רלוונטי

כן

PostFlow

המאפיין הזה מגדיר את המדיניות בזרימת PostFlow של בקשה או תגובה.

לא רלוונטי

כן

HTTPProxyConnection הגדרת כתובת הרשת ונתיב ה-URI שמשויכים לשרת ה-proxy ל-API.

BasePath

מחרוזת חובה שמזהה באופן ייחודי את נתיב ה-URI שמשמש את Apigee לניתוב הודעות נכנסות אל proxy ה-API המתאים.

‫BasePath הוא מקטע URI (לדוגמה, /weather) שמצורף לכתובת ה-URL הבסיסית של proxy ל-API (לדוגמה, http://apifactory-test.apigee.net). הערך של BasePath חייב להיות ייחודי בסביבה. הייחודיות מאומתת כשנוצר או מיובא proxy ל-API.

שימוש בתו כללי בנתיבי בסיס

אפשר להשתמש בתו כללי לחיפוש '*' אחד או יותר בנתיבי הבסיס של proxy ל-API. לדוגמה, נתיב בסיסי של /team/*/members מאפשר ללקוחות לבצע קריאה ל-https://[host]/team/blue/members ול-https://[host]/team/green/members בלי שתצטרכו ליצור שרתי proxy חדשים של API כדי לתמוך בצוותים חדשים. שימו לב: לא ניתן להשתמש ב-/**/.

חשוב: ב-Apigee אין תמיכה בשימוש בתו כללי '*' כרכיב הראשון של נתיב בסיס. לדוגמה, אין תמיכה ב-/*/search. התחלת נתיב הבסיס ב-'*' עלולה לגרום לשגיאות לא צפויות בגלל האופן שבו Apigee מזהה נתיבים תקינים.

כן

Properties

אפשר להגדיר קבוצה של הגדרות אופציונליות של HTTP כמאפיינים של <ProxyEndpoint>. המאפיינים הזמינים כוללים את האפשרויות הבאות:

request.queryparams.ignore.content.type.charset

משתמשים במאפיין request.queryparams.ignore.content.type.charset כדי להורות ל-proxy להתעלם מהפרמטר charset של הכותרת Content-Type כשמעבדים את כתובת ה-URL של הבקשה. לדוגמה:

<Properties>
  <Property name="request.queryparams.ignore.content.type.charset">true</Property>
</Properties>

בטבלה הבאה מוצגת דוגמה לפלט בהתאם להגדרה של המאפיין charset ולנוכחות הפרמטר charset של הכותרת Content-Type.

הגדרת נכס	ערך כותרת	פלט לדוגמה
`charset=false`	`charset` param not set	john.doe+test@gmail.com
`charset=false`	`charset=utf-8`	john.doe test@gmail.com
‫`charset=true` ואין פרמטר `charset` בכותרת.	`charset` param not set	john.doe+test@gmail.com
`charset=true`	`charset=utf-8` param set	john.doe+test@gmail.com

request.payload.parse.limit
משתמשים במאפיין request.payload.parse.limit כדי להגדיר את הגודל המקסימלי של מטען ייעודי (payload) שאפשר לעבד בתהליך הבקשה, במגה-בייט (M).

לדוגמה:
```
<Properties>
  <Property name="request.payload.parse.limit">30M</Property>
</Properties>
```
המגבלה המינימלית שאפשר להגדיר היא 10M והמגבלה המקסימלית שאפשר להגדיר היא 30M. אם המאפיין לא מוגדר, מגבלת ברירת המחדל היא 10 מיליון.

מידע נוסף זמין במאמר בנושא גודל מטען ייעודי (payload) של הודעה.

לא רלוונטי

לא

FaultRules

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

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

מידע נוסף על טיפול בתקלות

לא רלוונטי

לא

DefaultFaultRule

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

מידע נוסף על טיפול בתקלות

לא רלוונטי

לא

RouteRule האלמנט הזה מגדיר את היעד של הודעות בקשה נכנסות אחרי העיבוד שלהן בצינור הבקשות של ProxyEndpoint. בדרך כלל, RouteRule מצביע על נקודת קצה (endpoint) של יעד עם שם, על IntegrationEndpoint או על כתובת URL.

Name מאפיין חובה שמספק שם ל-RouteRule. התווים שמותר להשתמש בהם בשם מוגבלים לתווים הבאים: A-Za-z0-9._\-$ %. לדוגמה, Cat2 %_ הוא שם חוקי. לא רלוונטי כן

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

TargetEndpoint

מחרוזת אופציונלית שמזהה הגדרה של TargetEndpoint עם שם. נקודת קצה של יעד עם שם היא כל נקודת קצה של יעד שמוגדרת באותו proxy ל-API בספרייה /targets.

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

נקודת קצה של שרת proxy עשויה לקרוא לכתובת URL ישירות. לדוגמה, משאב JavaScript או Java, שפועל בתפקיד של צד הלקוח ב-HTTP, עשוי לבצע את המשימה הבסיסית של נקודת קצה של יעד, שהיא העברת בקשות לשירות לקצה העורפי.

לא רלוונטי

לא

URL מחרוזת אופציונלית שמגדירה כתובת רשת יוצאת שנקראת על ידי נקודת הקצה של ה-proxy, תוך דילוג על הגדרות TargetEndpoint שאולי מאוחסנות בתיקייה /targets לא רלוונטי לא

איך מגדירים RouteRules

נקודת קצה של יעד עם שם מתייחסת לקובץ תצורה ב-/apiproxy/targets שאליו הכלל RouteRule מעביר בקשה אחרי העיבוד על ידי נקודת הקצה של ה-proxy.

לדוגמה, RouteRule הבא מתייחס להגדרה /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

הפעלה ישירה של כתובת URL

נקודת קצה של שרת proxy יכולה גם להפעיל ישירות שירות לקצה העורפי. הפעלה ישירה של כתובת URL עוקפת כל הגדרה של TargetEndpoint עם שם בקטע /apiproxy/targets. לכן, TargetEndpoint היא הגדרה אופציונלית של שרת proxy ל-API, למרות שבפועל לא מומלץ להפעיל ישירות מנקודת הקצה של ה-proxy.

לדוגמה, הכלל RouteRule הבא מבצע קריאת HTTP אל http://api.mycompany.com/v2.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

מסלולים מותנים

אפשר לשרשר RouteRules כדי לתמוך בניווט דינמי בזמן ריצה. אפשר לנתב בקשות נכנסות להגדרות TargetEndpoint עם שם, ישירות לכתובות URL או לשילוב של שתי האפשרויות, על סמך כותרות HTTP, תוכן ההודעה, פרמטרים של שאילתות או מידע הקשרי כמו השעה ביום, הלוקאל וכו'.

כללי RouteRule מותנים פועלים כמו הצהרות מותנות אחרות ב-Apigee. מידע נוסף מופיע במאמרים בנושא הפניה לתנאים והפניה למשתני זרימה.

לדוגמה, השילוב הבא של RouteRule קודם כל מעריך את הבקשה הנכנסת כדי לאמת את הערך של כותרת HTTP. אם כותרת ה-HTTP‏ routeTo מכילה את הערך TargetEndpoint1, הבקשה מועברת לנקודת הקצה של היעד שנקראת TargetEndpoint1. אם לא, הבקשה הנכנסת מועברת אל http://api.mycompany.com/v2.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

מסלולי Null

אפשר להגדיר RouteRule עם ערך null כדי לתמוך בתרחישים שבהם אין צורך להעביר את הודעת הבקשה לנקודת היעד. האפשרות הזו שימושית כשנקודת הקצה של ה-proxy מבצעת את כל העיבוד הנדרש, למשל באמצעות JavaScript כדי לקרוא לשירות חיצוני או לאחזר נתונים מחיפוש במאגר של Apigee של זוגות מפתח/ערך.

לדוגמה, ההגדרה הבאה מגדירה נתיב null:

<RouteRule name="GoNowhere"/>

מסלולי null מותנים יכולים להיות שימושיים. בדוגמה הבאה, מוגדר מסלול null לביצוע כשכותרת HTTP‏ request.header.X-DoNothing מקבלת ערך שונה מ-null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

חשוב לזכור שאפשר לשרשר RouteRules, ולכן Route עם ערך null בתנאי יהיה בדרך כלל רכיב אחד מתוך קבוצה של RouteRules שנועדו לתמוך בניתוב מותנה.

שימוש מעשי בנתיב null מותנה יכול להיות לתמיכה בשמירה במטמון. באמצעות הערך של המשתנה שמוגדר על ידי מדיניות המטמון, אפשר להגדיר proxy ל-API שיבצע את המסלול null כשערך מוגש מהמטמון.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

נקודת קצה של יעד היא המקבילה היוצאת של נקודת קצה של שרת proxy. נקודת קצה יעד פועלת כלקוח של שירות לקצה העורפי או API – היא שולחת בקשות ומקבלת תשובות.

לפרוקסי של API לא חייבות להיות נקודות קצה של יעד. אפשר להגדיר נקודות קצה של proxy כדי לקרוא לכתובות URL ישירות. proxy ל-API ללא נקודות קצה של יעד בדרך כלל מכיל נקודת קצה של proxy שקוראת ישירות לשירות לקצה העורפי, או שמוגדרת לקרוא לשירות באמצעות Java או JavaScript.

הגדרת TargetEndpoint

`/targets/default.xml`

נקודת הקצה של היעד מגדירה את החיבור היוצא מ-Apigee לשירות או למשאב אחר.

דוגמה להגדרת TargetEndpoint:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <EventFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

רכיבי ההגדרה של TargetEndpoint

נקודת קצה של יעד יכולה לקרוא ליעד באחת מהדרכים הבאות:

‫HTTPTargetConnection לקריאות HTTP או HTTPS
‫LocalTargetConnection לשרשור מקומי של שרתי proxy

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

שם	תיאור	ברירת מחדל	חובה?
`TargetEndpoint`
`name`	השם של נקודת הקצה של היעד, שחייב להיות ייחודי בהגדרת ה-proxy ל-API. השם של נקודת הקצה של היעד משמש ב-RouteRule של ProxyEndpoint כדי להפנות בקשות לעיבוד יוצא. מותר להשתמש רק בתווים הבאים בשם: `A-Za-z0-9._\-$ %`.	לא רלוונטי	כן
`PreFlow`	ההגדרה הזו מגדירה את כללי המדיניות בזרימת PreFlow של בקשה או תגובה.	לא רלוונטי	כן
`Flows`	המאפיין מגדיר את המדיניות בזרימות מותנות של בקשה או תגובה.	לא רלוונטי	כן
`PostFlow`	המאפיין הזה מגדיר את המדיניות בזרימת PostFlow של בקשה או תגובה.	לא רלוונטי	כן
`EventFlow`	המאפיין מגדיר את המדיניות בתהליך EventFlow של תגובה. ה-EventFlow משמש להזרמת אירועים שנשלחים מהשרת. מידע נוסף זמין במאמר בנושא סטרימינג של אירועים שנשלחים מהשרת.	לא רלוונטי	לא
`HTTPTargetConnection`	מציין משאב בקצה העורפי שאליו מגיעים דרך HTTP, יחד עם רכיבי הצאצא שלו. אם משתמשים ב-HTTPTargetConnection, לא צריך להגדיר סוגים אחרים של חיבורי יעד (ScriptTarget או LocalTargetConnection). הערה: רכיבי `<LocalTargetConnection>` תומכים בתכונת החלפת המחרוזות הדינמית שנקראת תבניות הודעות. אפשר להשתמש ברכיב הצאצא `<Authentication>` כדי לבצע קריאות מאומתות לשירותי Google או לשירותים מותאמים אישית שפועלים במוצרי Google Cloud מסוימים, כמו Cloud Functions ו-Cloud Run. כדי להשתמש ברכיב `<Authentication>`, צריך לבצע את שלבי ההגדרה והפריסה שמתוארים במאמר שימוש באימות של Google. אם המדיניות מוגדרת בצורה נכונה, היא יוצרת טוקן אימות ומוסיפה אותו לבקשת השירות. מידע נוסף זמין במאמר בנושא שימוש ברכיב `<Authentication>`.
`URL`	הגדרת כתובת הרשת של שירות לקצה העורפי שאליו נקודת היעד מעבירה הודעות בקשה.	לא רלוונטי	לא
`LoadBalancer`	הגדרה של תצורות TargetServer עם שמות. אפשר להשתמש בהגדרות TargetServer עם שם לאיזון עומסים, כדי להגדיר 2 חיבורים או יותר של נקודות קצה. אפשר גם להשתמש בשרתי יעד כדי להפריד בין הגדרות של proxy ל-API לבין כתובות URL של נקודות קצה ספציפיות של שירותי קצה עורפי.	לא רלוונטי	לא
`Properties`	אפשר להגדיר קבוצה של הגדרות אופציונליות של HTTP כמאפיינים של `<TargetEndpoint>`. משתמשים במאפיין `response.payload.parse.limit` כדי להגדיר את הגודל המקסימלי של מטען הייעודי (payload) שאפשר לעבד בתהליך התגובה, במגה-בייט (M). לדוגמה: <Properties> <Property name="response.payload.parse.limit">15M</Property> </Properties> המגבלה המינימלית שאפשר להגדיר היא 10M והמגבלה המקסימלית שאפשר להגדיר היא 30M. אם המאפיין לא מוגדר, מגבלת ברירת המחדל היא 10 מיליון. מידע נוסף זמין במאמר בנושא גודל מטען ייעודי (payload) של הודעה.	לא רלוונטי	לא
`SSLInfo`	אפשר להגדיר הגדרות TLS/SSL בנקודת קצה של יעד כדי לשלוט בחיבור TLS/SSL בין proxy ל-API לבין שירות היעד. מידע נוסף על הגדרת TLS/SSL TargetEndpoint הערה: האלמנט `<SSLInfo>` תומך בתכונה של החלפת מחרוזות דינמיות שנקראת תבניות הודעות.	לא רלוונטי	לא
`LocalTargetConnection`	בעזרת רכיבי הצאצא שלו, מציין משאב שאפשר להגיע אליו באופן מקומי, תוך דילוג על מאפייני רשת כמו איזון עומסים ומעבדי הודעות. כדי לציין את משאב היעד, צריך לכלול את רכיב הבן APIProxy (עם הרכיב ProxyEndpoint) או את רכיב הבן Path. מידע נוסף זמין במאמר בנושא שרשור של פרוקסי ל-API. אם משתמשים ב-LocalTargetConnection, לא מגדירים סוגים אחרים של חיבורי יעד (HTTPTargetConnection או ScriptTarget).
`APIProxy`	מציין את השם של proxy ל-API שישמש כיעד לבקשות. שרת ה-proxy של היעד חייב להיות באותו ארגון ובאותה סביבה כמו שרת ה-proxy ששולח את הבקשות. זוהי חלופה לשימוש באלמנט Path.	לא רלוונטי	לא
`ProxyEndpoint`	המאפיין הזה משמש עם APIProxy כדי לציין את השם של נקודת הקצה של ה-proxy של ה-proxy של היעד.	לא רלוונטי	לא
`Path`	מציין את נתיב נקודת הקצה של proxy ל-API שישמש כיעד לבקשות. פרוקסי היעד צריך להיות באותו ארגון ובאותה סביבה כמו הפרוקסי ששולח את הבקשות. זוהי חלופה לשימוש ב-APIProxy.	לא רלוונטי	לא
`FaultRules`	מגדיר איך נקודת הקצה של היעד מגיבה לשגיאה. כלל שגיאה מציין שני פריטים: תנאי שמציין את התקלה שיש לטפל בה על סמך הקטגוריה, קטגוריית המשנה או השם המוגדרים מראש של התקלה מדיניות אחת או יותר שמגדירה את ההתנהגות של כלל השגיאה עבור התנאי המתאים מידע נוסף על טיפול בתקלות	לא רלוונטי	לא
`DefaultFaultRule`	מטפל בכל השגיאות (מערכת, העברה, העברת הודעות או מדיניות) שלא מטופלות באופן מפורש על ידי FaultRule אחר. מידע נוסף על טיפול בתקלות	לא רלוונטי	לא

שימוש ברכיב `<Authentication>`

השימוש ברכיב <Authentication> במדיניות <TargetEndpoint> זהה לשימוש ברכיב <Authentication> במדיניות ServiceCallout. גם ב-<TargetEndpoint> וגם ב-ServiceCallout, ‏ <Authentication> הוא רכיב משנה של <HttpTargetConnection>. פרטים נוספים זמינים במאמר רכיב האימות בהפניה למדיניות ServiceCallout.

הפניה לשגיאות ברכיב `<Authentication>`

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

`<Authentication>` דוגמאות לרכיבים

בדוגמה הבאה מוצג אופן ההפעלה של שירות שפריסתו בוצעה ב-Cloud Run כיעד, באמצעות הרכיב Authentication ליצירת אסימון OpenID Connect שנדרש לאימות ההפעלה:

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

בדוגמה הבאה מוצג איך להפעיל TargetService שמפנה אל Cloud Run באמצעות רכיב Authentication כדי ליצור טוקן OpenID Connect שנדרש לאימות ההפעלה. רכיב HeaderName מוסיף את אסימון ה-Bearer שנוצר לכותרת בשם X-Serverless-Authorization שנשלחת למערכת היעד. אם הכותרת Authorization קיימת, היא לא משתנה ונשלחת גם בבקשה.

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

בדוגמה הבאה מוצג איך להפעיל TargetService שמפנה לשירות Secret Manager של Google. בדוגמה הזו, הרכיב GoogleAccessToken מוגדר ליצירת אסימון אימות של Google כדי לאמת את בקשת היעד:

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

בדוגמה הבאה אפשר לראות איך מגדירים אוטומטית את הקהל של GoogleIDToken. אם הערך של useTargetUrl הוא true והמשתנה שאליו מתבצעת ההפניה לא מוגדר כמשתנה תקין, כתובת ה-URL של היעד (לא כולל פרמטרים של שאילתה) משמשת כקהל. נניח שנתיב הבקשה הוא /foobar וכתובת ה-URL של שרת היעד היא https://xyz.com, הקהל של GoogleIDToken יוגדר אוטומטית ל-https://xyz.com/foobar.

משתמשי Apigee hybrid: אם אתם משתמשים ב-Apigee hybrid, שימו לב שהמאפיין useTargetUrl זמין ב-Apigee hybrid בגרסה 1.8 ובגרסאות מתקדמות יותר.

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

הגדרת TargetEndpoint של TLS/SSL

לנקודות קצה של יעד יש לעיתים קרובות צורך בניהול חיבורי HTTPS עם תשתית הטרוגנית של קצה עורפי. לכן, יש תמיכה במספר הגדרות של TLS/SSL.

חשוב: רשויות ציבוריות שמנפיקות אישורים (CA) מפסיקות לכלול את clientAuth השימוש המורחב במפתח (EKU) באישורי SSL/TLS העדכניים שמהימנים באופן ציבורי. השינוי הזה, שמתרחש בכל התעשייה, משפיע על הגדרות של פרוטוקול TLS הדדי (mTLS) ב-Apigee platform.

ב-Apigee נדרש ש-clientAuthEKU יהיה נוכח באישורי לקוח ללחיצות ידיים של mTLS. בלי EKU, חיבורי mTLS ייכשלו גם בתעבורה צפונה (מהלקוח אל Apigee) וגם בתעבורה דרומה (מ-Apigee אל הקצה העורפי). הסבר מפורט על הבעיה, ציר הזמן והפתרונות המומלצים מופיע בפוסט הזה בבלוג.

רכיבי ההגדרה של TargetEndpoint ב-TLS/SSL

שם	תיאור	ברירת מחדל	חובה?
`SSLInfo`	אפשר להשתמש בבלוק `<SSLInfo>` גם ל-TLS/SSL חד-כיווני וגם ל-TLS/SSL דו-כיווני.
`Enabled`	אם הערך הוא `true`, החיבור ליעד צריך להשתמש בפרוטוקול SSL בהתאם לפרמטרים אחרים שצוינו בבלוק `<SSLInfo>` הזה. אם המדיניות מוגדרת ל-`false`,‏ היא מציינת שחיבור היעד לא צריך להשתמש ב-SSL. עם זאת, אם בלוק `<HTTPTargetConnection>` המקיף מכיל רכיב `<URL>` שהערך שלו הוא מחרוזת שמתחילה ב-`https://`, פרוטוקול SSL ישמש גם אם הערך של `<Enabled>` הוא false. במקרה כזה, המערכת מתעלמת מכל הבלוק `<SSLInfo>`. לעומת זאת, אם יש אלמנט `<URL>` שמתחיל ב-`http://`, פרוטוקול ה-SSL לא ישמש גם אם `<Enabled>` הוא true.	FALSE	לא
`Enforce`	אכיפה של SSL מחמיר בין Apigee לבין הקצה העורפי של היעד. אם המדיניות מוגדרת לערך `true`, החיבורים ייכשלו ליעדים עם אישורים לא תקינים, אישורים שתוקפם פג, אישורים בחתימה עצמית, אישורים עם אי התאמה של שם המארח ואישורים עם שורש לא מהימן. מוחזר קוד כשל `4xx` או `5xx`. אם לא מוגדר ערך, או אם הערך הוא `false`, התוצאה של חיבורים לשרתי קצה בעורף עם אישורים בעייתיים תלויה בהגדרה של `<IgnoreValidationErrors>` (ראו בהמשך). תגובה של הצלחה (`2xx`) יכולה להתרחש בתנאים מסוימים, אם הערך של `<IgnoreValidationErrors>` מוגדר ל-`true`. אפשר לבטל את ההגדרה של השדה `Enforce` ברמת הסביבה באמצעות feature flag `SSLInfo.Enforce`. מידע נוסף על הגדרת אכיפת SSL ברמת הסביבה	`false`	לא
`TrustStore`	מאגר מפתחות שמכיל אישורי בסיס מהימנים של שרתים. ‫Apigee יתייחס למארח המרוחק כאל מארח מהימן אם שרשרת האישורים שהוא שולח מסתיימת באישור שכלול במאגר המפתחות הזה.	לא רלוונטי	לא
`ClientAuthEnabled`	אם הערך הוא `true`, מופעל TLS דו-כיווני (שנקרא גם Mutual TLS או mTLS) בין Apigee לבין הרשת השכנה המרוחקת – לקוח ה-API או קצה העורפי של היעד. כדי להפעיל TLS דו-כיווני, בדרך כלל צריך להגדיר גם truststore וגם keystore ב-Apigee.	`false`	לא
`KeyStore`	מאגר מפתחות שמכיל מפתחות פרטיים שמשמשים לאימות לקוח יוצא	לא רלוונטי	כן (אם ClientAuthEnabled הוא True)
`KeyAlias`	כינוי המפתח של המפתח הפרטי שמשמש לאימות לקוח יוצא	לא רלוונטי	כן (אם ClientAuthEnabled הוא True)
`IgnoreValidationErrors`	מציין אם המערכת מתעלמת משגיאות אימות. אם מערכת ה-Backend משתמשת ב-SNI ומחזירה אישור עם שם נושא ייחודי (DN) שלא תואם לשם המארח, אין אפשרות להתעלם מהשגיאה והחיבור נכשל. הערה: אם הערך של `<Enforce>` הוא `true`, המערכת מתעלמת מהערך של `<IgnoreValidationErrors>`.	`false`	לא
`Ciphers`	הצפנות נתמכות ל-TLS/SSL יוצא. אם לא מציינים צפנים, כל הצפנים שזמינים ל-JVM מותרים. כדי להגביל את הצפנות, מוסיפים את הרכיבים הבאים עם רשימה של הצפנות נתמכות: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>	לא רלוונטי	לא
`Protocols`	פרוטוקולים נתמכים ל-TLS/SSL של הודעות יוצאות. אם לא מציינים פרוטוקולים, כל הפרוטוקולים שזמינים ל-JVM מורשים. כדי להגביל פרוטוקולים, צריך לציין אותם באופן מפורש. לדוגמה, כדי לאפשר רק TLS v1.2 או TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols> הערה: אין תמיכה ב-TLS 1.0 ב-Apigee Hybrid לחיבורים דרומיים.	לא רלוונטי	לא
`CommonName`	‫Apigee בודק את הערך כאן מול השם הנפוץ (CN) או שמות הנושא החלופיים (SAN) באישור של עמית מרוחק.	לא רלוונטי	לא

ציון אכיפת SSL ברמת הסביבה

אם הערך של SSLInfo.Enforce הוא true או false, הערך שצוין מבטל את כל אפשרויות האכיפה המפורטות שצוינו בבלוקים של <SSLInfo> בהגדרות של TargetEndpoint או TargetServer.

אם לא מוגדר ערך ל-SSLInfo.Enforce, אכיפת ה-SSL נקבעת לפי הערכים שצוינו באמצעות הרכיב <Enforce> בתוך בלוקים נפרדים של <SSLInfo>. מידע נוסף זמין במאמר בנושא הגדרת TargetEndpoint של TLS/SSL.

בדוגמה הבאה, הערך SSLInfo.Enforce מוגדר ל-true. בפלט שמתקבל, אפשר לראות ש-SSL נאכף בסביבה שצוינה.

VALUE=true
curl -Ss -v -X PUT \
    "https://apigee.googleapis.com/v1/organizations/MYORG/environments/MYENV" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{
        "name": "MYENV",
        "properties": {
            "property": [{
                "name": "features.SSLInfo.Enforce",
                "value": "'"$VALUE"'"
            }]
        }
    }'

פלט:

{
  ...
  "properties": {
    "property": [
      {
        "name": "features.SSLInfo.Enforce",
        "value": "true"
      }
    ]
  },
  ...
}

דוגמה לנקודת קצה של יעד שמופעל בה אימות של לקוח לדואר יוצא

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <Enforce>true</Enforce>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

הוראות מפורטות זמינות במאמר בנושא אפשרויות להגדרת TLS.

שימוש במשתני זרימה כדי להגדיר ערכי TLS/SSL באופן דינמי

אפשר גם להגדיר באופן דינמי את פרטי ה-TLS/SSL כדי לתמוך בדרישות גמישות של זמן ריצה. לדוגמה, אם ה-proxy ל-API מתחבר לשני יעדים שונים פוטנציאליים (יעד בדיקה ויעד ייצור), אפשר להגדיר את ה-proxy ל-API כך שיזהה באופן פרוגרמטי את הסביבה שהוא קורא לה ויגדיר באופן דינמי הפניות למאגר המפתחות ול-truststore המתאימים. במאמר בקהילת Apigee מוסבר התרחיש הזה בפירוט רב יותר, ומוצגות דוגמאות של שרתי proxy של API שאפשר לפרוס. Dynamic SSLInfo for TargetEndpoint using variable reference

בדוגמה הבאה להגדרת תג <SSLInfo> בהגדרת TargetEndpoint, אפשר לספק את הערכים בזמן הריצה, למשל באמצעות Java Callout, מדיניות JavaScript או מדיניות AssignMessage. משתמשים במשתני ההודעה שמכילים את הערכים שרוצים להגדיר.

אפשר להשתמש במשתנים רק ברכיבים הבאים.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

שימוש בהפניות כדי להגדיר ערכי TLS/SSL באופן דינמי

כשמגדירים נקודת קצה של יעד שמשתמשת ב-HTTPS, צריך לקחת בחשבון את המקרה שבו אישור ה-TLS/SSL יפוג, או ששינוי בהגדרת המערכת ידרוש עדכון של האישור.

מידע נוסף זמין במאמר בנושא טיפול באישורים שתוקפם פג.

עם זאת, אפשר להגדיר את נקודת הקצה של היעד כך שתשתמש בהפניה למאגר המפתחות או למאגר האישורים במקום זאת. היתרון בשימוש בהפניה הוא שאפשר לעדכן את ההפניה כך שתצביע על מאגר מפתחות או מאגר אישורים אחרים כדי לעדכן את אישור ה-TLS/SSL בלי להפעיל מחדש את מעבדי ההודעות.

לדוגמה, בהמשך מוצגת נקודת קצה לטירגוט שמשתמשת בהפניה למאגר המפתחות:

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>false</ClientAuthEnabled>
  <KeyStore>ref://keystoreref</KeyStore>
  <KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>

כדי ליצור את ההפניה שנקראת keystoreref, משתמשים בקריאה הבאה ל-POST API:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

‫$TOKEN מוגדר לאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר קבלת אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

ההפניה מציינת את השם של מאגר המפתחות ואת הסוג שלו.

כדי לראות את ההפניה, משתמשים בקריאה הבאה ל-API מסוג GET:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

כדי לשנות את ההפניה כך שתצביע על מאגר מפתחות אחר, ולוודא שהכינוי הוא בעל אותו שם, משתמשים בקריאת ה-PUT הבאה:

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

‫TargetEndpoint עם איזון עומסים

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

הוראות מפורטות זמינות במאמר בנושא איזון עומסים בשרתי קצה עורפיים.

IntegrationEndpoint

‫IntegrationEndpoint היא נקודת קצה יעד שמריצה באופן ספציפי שילובים של Apigee. אם הגדרתם IntegrationEndpoint, ‏ Apigee שולח את אובייקט הבקשה לפלטפורמת האינטגרציה של Apigee לביצוע. כדי להפעיל את השילוב, בנוסף להגדרת IntegrationEndpoint, צריך גם להוסיף את המדיניות SetIntegrationRequest לזרימת הנתונים של ה-proxy.

אפשר להגדיר את השילוב כך שיפעל באופן סינכרוני או אסינכרוני. לשם כך, צריך להגדיר את הרכיב <AsyncExecution> בהגדרות של IntegrationEndpoint. מידע נוסף זמין במאמר הבדלים בין ביצוע סינכרוני לביצוע אסינכרוני. אחרי שמריצים את השילוב, Apigee שומר את התגובה בהודעת התגובה.

הערה: כדי להפעיל את IntegrationEndpoint, צריך טוקן אימות. עם זאת, אין רכיב <Authentication> מפורש בהגדרה של IntegrationEndpoint. מערכת Apigee מוסיפה טוקן אימות לבקשה מאחורי הקלעים. כדי שהרכיב IntegrationEndpoint יאומת בהצלחה, צריך לפרוס את ה-proxy ל-API עם חשבון שירות שיש לו את תפקידי ה-IAM הנדרשים להפעלת שילוב. מידע על התפקידים הנדרשים מופיע במאמר תפקידי IAM לאינטגרציות. פרטים נוספים על פריסת proxy ל-API זמינים במאמר פריסה ב-Apigee.

הגדרת IntegrationEndpoint

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

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

בהגדרות לדוגמה של ProxyEndpoint, מערכת Apigee מבצעת את המשימות הבאות:

ב-PreFlow, המדיניות בשם my-set-integration-request-policy מופעלת, ומגדירה את אובייקט בקשת השילוב ואת משתני זרימת השילוב.
הפונקציה משתמשת ב-my-int-endpoint כנקודת הקצה של היעד, כפי שמצוין ב-RouteRule.
קריאה של אובייקט בקשת השילוב שנוצר על ידי my-set-integration-request-policy.
הבקשה נשלחת אל פלטפורמת השילוב של Apigee באמצעות אובייקט הבקשה ומשתני התהליך שהוגדרו על ידי מדיניות SetIntegrationRequest.
שומר את התשובה של השילוב בהודעת התשובה.

קובץ ה-XML שמכיל את ההצהרה <IntegrationEndpoint> יהיה זמין בספרייה APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/. אם יוצרים את ה-proxy ל-API באמצעות האפשרות Develop > API Proxies > CREATE NEW > Integration target, המערכת של Apigee מאחסנת את ההצהרה בקובץ /apiproxy/integration-endpoints/default.xml. אם יוצרים את קובץ ה-XML של נקודת הקצה לשילוב דרך ממשק המשתמש, אפשר לציין שם מותאם אישית לקובץ ה-XML.

בדוגמה הבאה מוצגת ההצהרה של רכיב <IntegrationEndpoint> בקובץ ה-XML:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

רכיבי ההגדרה של IntegrationEndpoint

שם	תיאור	ברירת מחדל	חובה?
`IntegrationEndpoint`
`name`	השם של IntegrationEndpoint. התווים שאפשר להשתמש בהם בשם מוגבלים לתווים הבאים: `A-Za-z0-9._\-$ %`	לא רלוונטי	כן
`AsyncExecution`	ערך בוליאני שמציין אם האינטגרציה צריכה לפעול במצב סינכרוני או אסינכרוני. מידע נוסף זמין במאמר הבדלים בין ביצוע סינכרוני לביצוע אסינכרוני.	FALSE	לא

ביצוע סינכרוני לעומת ביצוע אסינכרוני

אפשר להגדיר את השילוב כך שיפעל במצב סינכרוני או אסינכרוני. כדי להבין את ההבדל בין מצבי ביצוע סינכרוניים ואסינכרוניים, אפשר לעיין במאמר בנושא <AsyncExecution>.

משתמשים באלמנט <AsyncExecution> בתוך </IntegrationEndpoint> כדי לציין ביצוע סינכרוני או אסינכרוני. אם מגדירים את <AsyncExecution> ל-true, השילוב פועל באופן אסינכרוני. ואם מגדירים את הערך false, השילוב פועל באופן סינכרוני.

בדוגמה הבאה, הערך של AsyncExecution מוגדר ל-true:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

מדיניות

הספרייה /policies ב-proxy ל-API מכילה את כל כללי המדיניות שאפשר לצרף ל-Flows ב-proxy ל-API.

רכיבים של הגדרת מדיניות

שם	תיאור	ברירת מחדל	חובה?
`Policy`
`name`	השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל: `A-Za-z0-9._\-$ %`. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים. אופציונלי: אפשר להשתמש ברכיב `<DisplayName>` כדי להוסיף תווית למדיניות בכלי לעריכת ה-proxy בממשק המשתמש של Apigee עם שם אחר בשפה טבעית.	לא רלוונטי	כן
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	`true`	לא
`continueOnError`	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת.	`false`	לא
`async`	הערה: המאפיין הזה לא גורם להרצת המדיניות באופן אסינכרוני. ברוב המקרים, משאירים את הערך שמוגדר כברירת מחדל, `false`. כשהמדיניות מוגדרת לערך `true`, הביצוע שלה מועבר ל-thread אחר, כך שה-thread הראשי פנוי לטפל בבקשות נוספות. כשתהליך העיבוד אופליין מסתיים, השרשור הראשי חוזר ומסיים את הטיפול בזרימת ההודעות. במקרים מסוימים, הגדרת הערך `true` ל-async משפרת את הביצועים של proxy ל-API. עם זאת, שימוש יתר באסינכרוני עלול לפגוע בביצועים בגלל מעבר תכוף מדי בין השרשורים. כדי להשתמש בהתנהגות אסינכרונית בשרתי proxy של API, אפשר לעיין במאמר בנושא מודל אובייקטים של JavaScript.	`false`	לא

צירוף מדיניות

בתמונה הבאה מוצג רצף הביצוע של זרימות ה-proxy ל-API:

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

כפי שמוצג למעלה:

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

<Step><Name>MyPolicy</Name></Step>

האכיפה של המדיניות מתבצעת לפי הסדר שבו היא מצורפת ל-Flow. לדוגמה:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

רכיבי ההגדרה של צירוף מדיניות

שם	תיאור	ברירת מחדל	חובה?
`Step`
`Name`	השם של המדיניות שתופעל על ידי הגדרת השלב הזה.	לא רלוונטי	כן
`Condition`	משפט מותנה שקובע אם המדיניות נאכפת או לא. אם למדיניות יש תנאי משויך, המדיניות תופעל רק אם המשפט המותנה יחזיר את הערך True.	לא רלוונטי	לא

Flows

‫ProxyEndpoint ו-TargetEndpoint מגדירים צינור לעיבוד של הודעות בקשה ותגובה. צינור עיבוד מורכב מזרימת בקשות ומזרימת תגובות. כל תהליך של בקשה ותהליך של תגובה מחולקים לתהליך PreFlow, לתהליך PostFlow ולתהליך conditional או named אחד או יותר (אופציונלי).

‫PreFlow: תמיד מופעל. הפעולה מתבצעת לפני כל זרימת נתונים מותנית.
PostFlow: תמיד מופעל. הפעולה מתבצעת אחרי כל זרימות התנאים.

בנוסף, אפשר להוסיף PostClientFlow לנקודת הקצה של ה-proxy, שמופעל אחרי שהתשובה מוחזרת לאפליקציית הלקוח ששלחה את הבקשה. אפשר לצרף ל-flow הזה רק את המדיניות MessageLogging. התכונה PostClientFlow מפחיתה את זמן האחזור של proxy ל-API ומאפשרת לכלול ביומן מידע שלא מחושב עד שהתגובה מוחזרת ללקוח, כמו client.sent.start.timestamp ו-client.sent.end.timestamp.התכונה משמשת בעיקר למדידת מרווח הזמן בין חותמות הזמן של ההתחלה והסיום של הודעת התגובה.

דוגמה ל-PostClientFlow עם מדיניות של רישום הודעות שמצורפת אליו.

...
  <PostFlow name="PostFlow">
      <Request/>
      <Response/>
  </PostFlow>
  <PostClientFlow>
      <Request/>
      <Response>
          <Step>
              <Name>Message-Logging-1</Name>
          </Step>
      </Response>
  </PostClientFlow>
  ...

צינור העיבוד של proxy ל-API מפעיל את רכיבי ה-Flow ברצף הבא:

צינור בקשות:

Proxy Request PreFlow
תהליכים מותנים של בקשות משרת proxy (אופציונלי)
Proxy Request PostFlow
Target Request PreFlow
תהליכים מותנים של בקשות לטירגוט (אופציונלי)
Target Request PostFlow

צינור עיבוד נתונים לתגובה:

Target Response PreFlow
תהליכים מותנים של תשובות יעד (אופציונלי)
Target Response PostFlow
Proxy Response PreFlow
תהליכים מותנים של תגובת שרת proxy (אופציונלי)
Proxy Response PostFlow
תגובה של PostClientFlow (אופציונלי)

צריך להגדיר בהגדרות של ProxyEndpoint או TargetEndpoint רק את רכיבי Flow שיש להם קבצים מצורפים של מדיניות. צריך לציין PreFlow ו-PostFlow רק בתצורת ProxyEndpoint או TargetEndpoint כשצריך לאכוף מדיניות במהלך העיבוד של PreFlow או PostFlow.

בניגוד לזרימות מותנות, הסדר של רכיבי PreFlow ו-PostFlow לא חשוב – proxy ה-API תמיד יבצע כל אחד מהם בנקודה המתאימה בצינור, בלי קשר למיקום שבו הם מופיעים בהגדרת נקודת הקצה.

תהליכי עבודה מותנים

נקודות קצה של Proxy ונקודות קצה של יעד תומכות במספר בלתי מוגבל של זרימות מותנות (שנקראות גם זרימות עם שם).

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

הגדרת זרימות מותנות מאפשרת להחיל שלבי עיבוד ב-proxy ל-API על סמך:

URI של בקשה
פועל HTTP ‏ (GET/PUT/POST/DELETE)
ערך של פרמטר שאילתה, כותרת ופרמטר טופס
סוגים רבים אחרים של תנאים

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

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request>
  </Flow>
</Flows>

רכיבי ההגדרה של תהליך

שם	תיאור	ברירת מחדל	חובה?
`Flow`	צינור לעיבוד בקשות או תגובות שמוגדר על ידי נקודת קצה (endpoint) של שרת proxy או נקודת קצה (endpoint) של יעד
`Name`	השם הייחודי של התהליך.	לא רלוונטי	כן
`Condition`	משפט מותנה שבודק אם ערך של משתנה אחד או יותר הוא True או False. בכל רכיבי ה-Flow, מלבד הסוגים המוגדרים מראש PreFlow ו-PostFlow, צריך להגדיר תנאי לביצוע שלהם. עם זאת, אם כוללים רצף של זרימות ובסופו זרימה אחת ללא תנאי, היא תפעל כמו הצהרת Else בסוף הרצף.	לא רלוונטי	כן
`Request`	הצינור שמשויך לעיבוד של הודעות בקשה	לא רלוונטי	לא
`Response`	הצינור שמשויך לעיבוד של הודעות תגובה	לא רלוונטי	לא

עיבוד שלבים

הסדר הרציף של Flows מותנים נאכף על ידי Apigee. הזרימות המותנות מופעלות מלמעלה למטה. התהליך המותנה הראשון שהתנאי שלו מוערך כ-true מופעל, ורק תהליך מותנה אחד מופעל.

לדוגמה, בהגדרת ה-Flow הבאה, כל בקשה נכנסת שלא כוללת את סיומת הנתיב /first או /second תגרום להרצת ThirdFlow, וכך תיאכף המדיניות שנקראת Return404.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

משאבים

'משאבים' (קבצי משאבים לשימוש בשרתי proxy ל-API) הם סקריפטים, קוד וטרנספורמציות XSL שאפשר לצרף ל-Flows באמצעות מדיניות. הם מופיעים בקטע Scripts בכלי לעריכת שרת proxy של API בממשק המשתמש של Apigee.

במאמר ניהול משאבים מפורטים סוגי המשאבים הנתמכים.

אפשר לאחסן משאבים ב-proxy ל-API, בסביבה או בארגון. בכל מקרה, משאב מוזכר בשם במדיניות. ‫Apigee פותר את השם על ידי מעבר מ-API Proxy, לסביבה ולרמת הארגון.

אפשר להפנות למשאב שמאוחסן ברמת הארגון ממדיניות בכל סביבה. אפשר להפנות למשאב שמאוחסן ברמת הסביבה באמצעות מדיניות באותה סביבה. אפשר להפנות למשאב שמאוחסן ברמת ה-proxy ל-API רק באמצעות מדיניות באותו proxy ל-API.

הפניה להגדרת proxy ל-API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבנה ספריות של הגדרות proxy ל-API

הגדרה בסיסית

/apiproxy/weatherapi.xml

רכיבי הגדרה בסיסיים

ProxyEndpoint

/apiproxy/proxies/default.xml

רכיבי ההגדרה של ProxyEndpoint

איך מגדירים RouteRules

הפעלה ישירה של כתובת URL

מסלולים מותנים

מסלולי Null

TargetEndpoint

הגדרת TargetEndpoint

/targets/default.xml

רכיבי ההגדרה של TargetEndpoint

שימוש ברכיב <Authentication>

הפניה לשגיאות ברכיב <Authentication>

<Authentication> דוגמאות לרכיבים

הגדרת TargetEndpoint של TLS/SSL

רכיבי ההגדרה של TargetEndpoint ב-TLS/SSL

ציון אכיפת SSL ברמת הסביבה

דוגמה לנקודת קצה של יעד שמופעל בה אימות של לקוח לדואר יוצא

שימוש במשתני זרימה כדי להגדיר ערכי TLS/SSL באופן דינמי

שימוש בהפניות כדי להגדיר ערכי TLS/SSL באופן דינמי

‫TargetEndpoint עם איזון עומסים

IntegrationEndpoint

הגדרת IntegrationEndpoint

רכיבי ההגדרה של IntegrationEndpoint

ביצוע סינכרוני לעומת ביצוע אסינכרוני

מדיניות

רכיבים של הגדרת מדיניות

צירוף מדיניות

רכיבי ההגדרה של צירוף מדיניות

Flows

תהליכי עבודה מותנים

רכיבי ההגדרה של תהליך

עיבוד שלבים

משאבים

הפניה להגדרת proxy ל-API

`/apiproxy/weatherapi.xml`

`/apiproxy/proxies/default.xml`

`/targets/default.xml`

שימוש ברכיב `<Authentication>`

הפניה לשגיאות ברכיב `<Authentication>`

`<Authentication>` דוגמאות לרכיבים