Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הפניה להגדרת 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`	מספר הגרסה של הגדרת ה-API Proxy. אין צורך להגדיר במפורש את מספר הגרסה, כי Apigee עוקב באופן אוטומטי אחרי הגרסה הנוכחית של ה-API Proxy.	לא רלוונטי	לא
`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. זו פשוט הגדרת manifest, שנועדה לספק שקיפות לגבי התוכן של ה-proxy ל-API.	לא רלוונטי	לא
`TargetEndpoints`	רשימה של נקודות קצה של היעד בספרייה `/targets` של שרת ה-proxy ל-API הזה. בדרך כלל רואים את הרכיב הזה רק כששרת ה-proxy ל-API נוצר באמצעות ממשק המשתמש של Apigee. זו פשוט הגדרה של manifest, שנועדה לספק נראות של התוכן של שרת ה-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 לניתוב הודעות נכנסות אל שרת ה-API המתאים.

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

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

אפשר להשתמש בתו כללי אחד או יותר '*' בנתיבי הבסיס של פרוקסי API. לדוגמה, נתיב בסיס של /team/*/members מאפשר ללקוחות לבצע קריאה ל-https://[host]/team/blue/members ול-https://[host]/team/green/members בלי שתצטרכו ליצור פרוקסי 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`)	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>
```
הסף המינימלי שאפשר להגדיר הוא 10 מיליון, והסף המקסימלי שאפשר להגדיר הוא 30 מיליון. אם הנכס לא מוגדר, סף ברירת המחדל הוא 10 מיליון.

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

לא רלוונטי

לא

FaultRules

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

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

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

לא רלוונטי

לא

DefaultFaultRule

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

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

לא רלוונטי

לא

RouteRule הגדרה של היעד של הודעות בקשה נכנסות אחרי העיבוד על ידי צינור הבקשות של ProxyEndpoint. בדרך כלל, RouteRule מצביע על נקודת קצה של יעד עם שם, על 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 – היא שולחת בקשות ומקבלת תשובות.

לא חייבים להגדיר נקודות קצה של יעד ל-proxy ל-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 לשרת proxy

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

שם	תיאור	ברירת מחדל	חובה?
`TargetEndpoint`
`name`	השם של נקודת הקצה של היעד, שחייב להיות ייחודי בתצורת ה-proxy ל-API. השם של נקודת הקצה של היעד משמש ב-ProxyEndpoint RouteRule כדי להפנות בקשות לעיבוד יוצא. מותר להשתמש רק בתווים הבאים בשם: `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> הסף המינימלי שאפשר להגדיר הוא 10 מיליון, והסף המקסימלי שאפשר להגדיר הוא 30 מיליון. אם הנכס לא מוגדר, סף ברירת המחדל הוא 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 של היעד.	לא רלוונטי	לא
`Path`	מציין את נתיב נקודת הקצה של שרת proxy ל-API שמשמש כיעד לבקשות. שרת ה-proxy של היעד חייב להיות באותו ארגון ובאותה סביבה כמו שרת ה-proxy ששולח את הבקשות. זוהי חלופה לשימוש ב-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 זמין בגרסה 1.8 של Apigee Hybrid ובגרסאות מתקדמות יותר.

<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.

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

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

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

שם	תיאור	ברירת מחדל	חובה?
`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 דו-כיווני (שנקרא גם 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 המתאימים. Dynamic SSLInfo for TargetEndpoint using variable reference במאמר בקהילת Apigee מוסבר התרחיש הזה בפירוט רב יותר, ומוצגות דוגמאות של שרתי proxy של API שאפשר לפרוס.

בדוגמה הבאה להגדרה של תג <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 הראשי פנוי לטפל בבקשות נוספות. כשהעיבוד במצב אופליין מסתיים, ה-thread הראשי חוזר ומסיים את הטיפול בזרימת ההודעות. במקרים מסוימים, הגדרת async ל-`true` משפרת את הביצועים של proxy ל-API. עם זאת, שימוש מוגזם ב-async עלול לפגוע בביצועים בגלל מעברים רבים מדי בין threads. כדי להשתמש בהתנהגות לא סנכרונית בשרתי 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.ה-flow משמש בעיקר למדידת מרווח הזמן בין חותמות הזמן של ההתחלה והסיום של הודעת התשובה.

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

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

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

פייפליין הבקשות:

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 רק את רכיבי Flows עם קבצים מצורפים של מדיניות. צריך לציין את 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. בכל התהליכים, מלבד סוגי PreFlow ו-PostFlow המוגדרים מראש, צריך להגדיר תנאי לביצוע. עם זאת, אם כוללים תהליך יחיד ללא תנאי בסוף רצף של תהליכים, הוא יפעל כמשפט Else בסוף רצף התהליכים.	לא רלוונטי	כן
`Request`	הצינור שמשויך לעיבוד של הודעות בקשה	לא רלוונטי	לא
`Response`	הצינור שמשויך לעיבוד של הודעת התגובה	לא רלוונטי	לא

עיבוד שלבים

הסדר הרציף של תהליכים מותנים נאכף על ידי 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

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

ציון אכיפת 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>` דוגמאות לרכיבים