אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.
כמפתחים שעובדים עם Apigee Edge, פעילויות הפיתוח הראשיות שלך כוללות הגדרת שרתי proxy של API שמשמשים כשרתי proxy עבור ממשקי API או שירותים לקצה העורפי. המסמך הזה הוא הפניה של כל רכיבי התצורה הזמינים כשבונים שרתי proxy של API.
אם אתם לומדים איך ליצור שרתי proxy של API, מומלץ להתחיל עם הנושא יצירת שרת proxy פשוט ל-API.
הדרכים הנפוצות ביותר לעריכת הגדרות של שרת proxy הן:
- שימוש בעורך XML בממשק המשתמש של Edge
- מורידים את ההגדרה ועורכים אותה באופן מקומי, כפי שמתואר בקטע פיתוח מקומי של הגדרות לשרת proxy.
פיתוח מקומי של הגדרות לשרת proxy
ניתן להוריד את הגדרות שרת ה-proxy כדי לערוך אותן במחשב מקומי. כשמסיימים, מעלים את התוצאות ל-Edge. הגישה הזו מאפשרת לשלב את ההגדרות האישיות של שרת ה-proxy באמצעות בקרת המקור, הגרסאות ותהליכי העבודה המשותפים האחרים. בנוסף, בעזרת הגדרה מקומית של שרת proxy, תוכלו להשתמש בעורך XML ובכלי האימות שלכם.
בקטע הזה מוסבר איך להשתמש בממשק המשתמש כדי להוריד תצורה קיימת של שרת proxy, לערוך אותה ואז להעלות אותה בחזרה ל-Edge לפריסה. ניתן גם להשתמש ב-apigeetool כדי להוריד ולפרוס תצורה חדשה של שרת proxy (באמצעות הפקודות fetchproxy
ו-deployproxy
, בהתאמה).
כדי לערוך הגדרות של שרת proxy באופן מקומי באמצעות ממשק המשתמש:
- מורידים את ההגדרה הנוכחית של שרת ה-proxy בממשק של Edge. (בתצוגה המפורטת של שרתי ה-API, בוחרים באפשרות Project > Download Revision.
- במחשב המקומי, יוצרים ספרייה חדשה ומרחיבים אליה את קובץ ה-ZIP.
כדי להרחיב את קובץ ה-ZIP, אפשר להשתמש בכלי שירות כמו
unzip
, כמו בדוגמה הבאה:mkdir myappdir
unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir
התוכן המורחב של קובץ ה-ZIP צריך להיות דומה למבנה שמתואר במבנה ה-proxy של ה-API.
- עורכים את קובצי המקור לפי הצורך. במאמר הגדרת תצורה ומבנה ספרייה של שרת proxy ל-API יש תיאור של קובצי המקור בהגדרה של שרת proxy.
לדוגמה, כדי להפעיל מעקב תקינות דרך שרת ה-proxy של ה-API, צריך לערוך את קובץ התצורה של EndEndpoint בספרייה
/apiproxy/targets/
. קובץ ברירת המחדל בספרייה הזו הואdefault.xml
, אבל אם תשתמשו ביעדים מותנים, ייתכן שיהיו קבצים עם שמות אחרים.במקרה הזה, אם קובץ התצורה של EndEndpoint והספרייה שלו לא קיימים, יוצרים אותם.
- לאחר סיום העריכה של קובצי התצורה של שרת ה-proxy, חשוב לשמור את השינויים.
- יש לעבור לספרייה החדשה שיצרת כשהרחבת את קובצי ה-ZIP (הבסיס של קובצי התצורה המורחבים).
למשל, אם הרחבת את הקבצים לספרייה
/myappdir
, יש להחליף לספרייה הזו כמו בדוגמה הבאה:cd myappdir
עליך לעבור לספרייה הזו לפני העברה לארכיון של קובצי התצורה של שרת ה-proxy, כי לא רוצה שהספרייה
/myappdir
תיכלל בקובץ ה-ZIP. הספרייה ברמה העליונה בקובץ ה-ZIP חייבת להיות/apiproxy
. - שולחים מחדש את קובצי התצורה של שרת ה-proxy, כולל הקבצים החדשים או ששונו. אפשר להשתמש
בכלי שירות כמו
zip
, כמו בדוגמה הבאה:zip my-new-proxy.zip -r .
הספרייה ברמה העליונה בקובץ ה-ZIP חייבת להיות
/apiproxy
.אין דרישות מיוחדות לשם קובץ ה-ZIP. לדוגמה, אין צורך להגדיל את מספר הגרסה או לציין את התאריך בשם הקובץ, אבל זה יכול לעזור בניפוי באגים או באמצעות בקרת מקור.
Edge מעלה את מספר הגרסאות האישיות של ההגדרות האישיות החדשות של שרת ה-proxy כשמעלים אותן.
- מעלים את ההגדרות החדשות של שרת ה-proxy באמצעות ממשק המשתמש של Edge. (בתצוגה שרת proxy, בוחרים באפשרות Project > Upload a New Edition).
אם מופיעה שגיאה כמו Bundle is invalid. Empty bundle., כדאי לוודא שהספרייה ברמה העליונה של קובץ ה-ZIP היא
/apiproxy
. אם לא, צריך להעביר לארכיון את קובצי ה-proxy האלה ברמה הבסיסית (root) של הספרייה המורחבת.אחרי שמעלים את ההגדרות החדשות של שרת ה-proxy, Edge מגדיל את מספר הגרסה ומציג אותה בתצוגה סיכום הגרסה.
Edge לא פורס את הגרסה החדשה בשבילכם אחרי שאתם מעלים אותה בממשק המשתמש.
- פריסת הגרסה החדשה.
מידע נוסף זמין במאמר הדרכה: איך להוריד שרת proxy באמצעות ממשק המשתמש וממשק ה-API לניהול בקהילת Apigee.
מבנה של שרת proxy ל-API
שרת proxy ל-API מורכב מהתצורה הבאה:
הגדרה בסיסית | הגדרות התצורה הראשיות של שרת proxy ל-API. למידע נוסף, ראו הגדרות בסיסיות. |
הגדרה של נקודת קצה (endpoint) | הגדרות לחיבור ה-HTTP הנכנס (מבקשת אפליקציות ועד Apigee Edge), תהליכי בקשה ותגובה וקבצים מצורפים. כדאי לעיין ב-ProxyEndpoint. |
הגדרה של נקודת קצה (endpoint) | הגדרות לחיבור ה-HTTP היוצא (מ-Apigee Edge לשירות לקצה העורפי), לתהליךי הבקשה והתגובה ולקבצים מצורפים של המדיניות. עיינו בקטע TargetEndpoint. |
פרחים | צינורות עיבוד נתונים של בקשות ושרתי proxy של נקודת קצה ויעד, שאליהם ניתן לצרף מדיניות. הצגה של זרימה. |
כללי המדיניות | קובצי תצורה בפורמט XML שתואמים לסכימות המדיניות של Apigee Edge. למידע נוסף, אפשר לעיין במדיניות. |
מקורות מידע | סקריפטים, קובצי JAR וקובצי XSLT שמתבצעת בהם הפניה למדיניות, שבהם יש ליישם לוגיקה מותאמת אישית. אפשר להיעזר במקורות מידע. |
המבנה של ספריית שרת ה-API והתוכן שלו
הרכיבים בטבלה שלמעלה מוגדרים באמצעות קובצי תצורה במבנה הספריות הבא:
קובצי תצורה ומבנה הספרייה בשרת proxy של API
הקטע הזה מסביר את קובצי התצורה ומבנה הספרייה של שרת proxy של API.
הגדרה בסיסית
/apiproxy/weatherapi.xml
ההגדרה הבסיסית של שרת proxy ל-API, שמגדיר את השם של שרת ה-API ל-API. השם חייב להיות ייחודי בארגון.
תצורה לדוגמה:
<APIProxy name="weatherapi"> </APIProxy>
אלמנטים של הגדרה בסיסית
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
APIProxy |
|||
name |
השם של שרת ה-API של API, שחייב להיות ייחודי בארגון. התווים המותרים בשם מוגבלים לתווים הבאים: A-Za-z0-9_- |
לא רלוונטי | כן |
revision |
מספר הגרסה של ההגדרות האישיות של שרת ה-API. אין צורך להגדיר במפורש את מספר הגרסה, כי Apigee Edge עוקב באופן אוטומטי אחרי הגרסה הנוכחית של שרת ה-API API. | לא רלוונטי | לא |
ConfigurationVersion |
הגרסה של סכימת התצורה של שרת ה-proxy של ה-API שאליה משויך שרת ה-API הזה. הערך הנתמך היחיד כרגע הוא majorVersion 4 ו-smallVersion 0. יכול להיות שנשתמש בהגדרה הזו בעתיד כדי לאפשר את ההתפתחות של פורמט ה-proxy של ה-API. | 4.0 | לא |
Description |
תיאור טקסטואלי של שרת ה-API API. אם תספק תיאור, הוא יוצג בממשק המשתמש לניהול Edge. | לא רלוונטי | לא |
DisplayName |
שם ידידותי למשתמש, שעשוי להיות שונה מהמאפיין name של ההגדרה של שרת proxy ל-API. |
לא רלוונטי | לא |
Policies |
רשימה של כללי מדיניות בספרייה /policies של שרת ה-API הזה של ה-API. בדרך כלל הרכיב הזה יופיע רק כאשר שרת ה-API של ה-API נוצר באמצעות ממשק המשתמש לניהול Edge.
ההגדרה הזו היא פשוט 'מניפסט', שנועדה לספק חשיפה לתוכן של שרת ה-proxy של ה-API. |
לא רלוונטי | לא |
ProxyEndpoints |
רשימה של ProxyEndpoints בספרייה /proxies של שרת ה-API הזה של ה-API. בדרך כלל הרכיב הזה יופיע רק כאשר שרת ה-API של ה-API נוצר באמצעות ממשק המשתמש לניהול Edge. זוהי פשוט הגדרה 'מניפסט', שנועדה לספק חשיפה לתוכן של שרת ה-proxy של ממשק ה-API. |
לא רלוונטי | לא |
Resources |
רשימה של משאבים (JavaScript, Python, Java, XSLT) בספרייה /resources של שרת ה-proxy הזה של ה-API. בדרך כלל הרכיב הזה יופיע רק כאשר שרת ה-API של ה-API נוצר באמצעות ממשק המשתמש לניהול Edge. ההגדרה הזו היא רק 'מניפסט', שמיועדת לספק חשיפה לתוכן של שרת ה-API של ה-API. |
לא רלוונטי | לא |
Spec |
מזהה את המפרט של OpenAPI שמשויך לשרת ה-API של ה-API. הערך
מוגדר לכתובת URL או לנתיב בחנות המפרט. הערה: חנות המפרטים זמינה רק בממשק החדש של Edge. מידע נוסף על חנות המפרטים זמין במאמר ניהול ושיתוף של מפרטים. |
לא רלוונטי | לא |
TargetServers |
רשימה של TargetServers שיש אליהם הפניה ב-TargetEndpoints של שרת ה-API הזה של ה-API. בדרך כלל הרכיב הזה יופיע רק כאשר שרת ה-API של ה-API נוצר באמצעות ממשק המשתמש לניהול Edge. ההגדרה הזו היא פשוט 'מניפסט', שנועדה לספק חשיפה לתוכן של שרת ה-proxy של ה-API. | לא רלוונטי | לא |
TargetEndpoints |
רשימה של TargetEndpoints בספרייה /targets של שרת ה-API הזה של ה-API. בדרך כלל הרכיב הזה יופיע רק כאשר שרת ה-API של ה-API נוצר באמצעות ממשק המשתמש לניהול Edge. זוהי פשוט הגדרה 'מניפסט', שנועדה לספק חשיפה לתוכן של שרת ה-proxy של ממשק ה-API. |
לא רלוונטי | לא |
נקודת קצה של שרת proxy
התמונה הבאה מציגה את תהליך הבקשה/תגובה:
/apiproxy/proxies/default.xml
ההגדרה של ProxyEndpoint מגדירה את הממשק של הכניסה הנכנסת (מול הלקוחות) לשרת proxy של API. כאשר מגדירים ProxyEndpoint, מתבצעת הגדרה של הרשת. היא מגדירה את האופן שבו אפליקציות של לקוחות ('אפליקציות') צריכות להפעיל את שרת ה-API של שרת ה-proxy.
ההגדרות הבאות של ProxyEndpoint יישמרו ב-/apiproxy/proxies
:
<ProxyEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPProxyConnection> <BasePath>/weather</BasePath> <VirtualHost>default</VirtualHost> </HTTPProxyConnection> <FaultRules/> <DefaultFaultRule/> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> </RouteRule> </ProxyEndpoint>
מרכיבי ההגדרה הנדרשים ב-ProxyEndpoint בסיסי הם:
אלמנטים של תצורת ProxyEndpoint
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
ProxyEndpoint |
|||
name |
השם של ProxyEndpoint. חייב להיות ייחודי בתצורת שרת ה-API של ה-API, כאשר (במקרים נדירים) מוגדרים כמה ProxyEndpoints. התווים המותרים בשם
מוגבלים לתווים הבאים: A-Za-z0-9._\-$ % . |
לא רלוונטי | כן |
PreFlow |
מגדיר את המדיניות בתהליך ה-PreFlow של בקשה או תגובה. | לא רלוונטי | כן |
Flows |
מגדיר את כללי המדיניות בהליכים המותנים של בקשה או תגובה.
|
לא רלוונטי | כן |
PostFlow |
מגדיר את המדיניות בתהליך ה-PostFlow של בקשה או תגובה.
|
לא רלוונטי | כן |
HTTPProxyConnection |
הגדרת כתובת הרשת ונתיב ה-URI המשויכים לשרת ה-API של ה-API | ||
BasePath |
מחרוזת נדרשת שמזהה באופן ייחודי את נתיב ה-URI המשמש את Apigee Edge לניתוב הודעות נכנסות לשרת proxy המתאים ל-API. BasePath הוא מקטע URI (למשל שימוש בתו כללי לחיפוש בנתיבים בסיסיים ניתן להשתמש בתווים כלליים לחיפוש "*" אחד או יותר בנתיבי בסיס של שרת proxy של API. לדוגמה, נתיב בסיס של חשוב: אי אפשר להשתמש בתו כללי לחיפוש "*" כרכיב הראשון
של הנתיב הבסיסי. לדוגמה: |
/ | כן |
VirtualHost |
משייכת שרת proxy של API לכתובות URL בסיסיות ספציפיות לסביבה. VirtualHost הוא הגדרה בעלת שם שמגדירה כתובת אתר אחת או יותר עבור סביבה. ה-VirtualHosts השמות המוגדרים עבור ProxyEndpoint קובעים את הדומיינים והיציאות שבהן חשוף שרת proxy של API, וכן, על ידי תוסף, את כתובת האתר שבה האפליקציות משתמשות כדי להפעיל שרת proxy. כברירת מחדל, יוגדרו שני סביבות אירוח וירטואליות בשם:
|
ברירת מחדל | לא |
Properties |
אפשר לקבוע קבוצה של הגדרות אופציונליות של HTTP בתור מאפיינים של
<ProxyEndpoint> . |
לא רלוונטי | לא |
FaultRules |
הגדרת האופן שבו שרת ה-ProxyEnd מגיב לשגיאה. כלל כשל מציין שני פריטים:
עיינו בקטע טיפול בשגיאות. |
לא רלוונטי | לא |
DefaultFaultRule |
טיפול בשגיאות (מערכת, תחבורה, העברת הודעות או מדיניות) שלא מטופלות באופן מפורש על ידי כלל תקלה אחר. עיינו בקטע טיפול בשגיאות. |
לא רלוונטי | לא |
RouteRule |
מגדיר את היעד של הודעות הבקשות הנכנסות לאחר העיבוד, על ידי צינור עיבוד הנתונים של שרת ה-proxy Endpoint. בדרך כלל ה-RoutRule מפנה לתצורה ייעודית בשם EndEndpoint, אבל הוא יכול גם להפנות ישירות לכתובת URL. | ||
Name |
מאפיין חובה שנותן שם ל-RouteRule. התווים שמותר להשתמש בשם שלהם מוגבלים לתווים הבאים: A-Za-z0-9._\-$ % . לדוגמה, Cat2 %_ הוא שם חוקי. |
לא רלוונטי | כן |
Condition |
הצהרת תנאי אופציונלית המשמשת לניתוב דינמי בזמן ריצה. לדוגמה, RouteRules מותנים יכולים לאפשר ניתוב מבוסס תוכן כדי לתמוך בגרסאות של הקצה העורפי. | לא רלוונטי | לא |
TargetEndpoint |
מחרוזת אופציונלית שמזהה תצורה בשם TargetEndpoint. נקודת קצה (endpoint) בעלת שם היא כל נקודת קצה (endEnd) שהוגדרה באותו שרת proxy של API תחת הספרייה כשנותנים שם ל-TargetEndpoint, צריך לציין לאן להעביר את ההודעות בזמן הטיפול בצינור עיבוד הנתונים של שרת ה-proxy. חשוב לשים לב שזו הגדרה אופציונלית. ProxyEnd יכול להתקשר ישירות לכתובת URL. לדוגמה, משאב של JavaScript או Java המשמש בתור לקוח HTTP יכול לבצע את תפקידו הבסיסי של יעד EndEnd, שהוא להעביר בקשות לשירות לקצה העורפי. |
לא רלוונטי | לא |
כתובת URL | מחרוזת אופציונלית שמגדירה כתובת רשת יוצאת שנקראת ProxyEndpoint, ועוקפת את כל הגדרות היעד של נקודות קצה שעשויות להיות מאוחסנות תחת /targets |
לא רלוונטי | לא |
הגדרת RouteRules
נקודת קצה (endpoint) בשם היא קובץ תצורה תחת /apiproxy/targets
שאליו ה-RouteRule מעביר בקשה לאחר עיבוד על ידי שרת ה-proxy.
לדוגמה, RouteRule הבא מתייחס להגדרה
/apiproxy/targets/myTarget.xml
:
<RouteRule name="default"> <TargetEndpoint>myTarget</TargetEndpoint> </RouteRule>
הפעלה של כתובת URL ישירה
ProxyEndpoint יכול גם להפעיל ישירות שירות לקצה עורפי. ההפעלה של כתובת URL ישירה עוקפת הגדרות של
EndEndpoints שנקראות בשם /apiproxy/targets
. לכן, TargetEndpoint הוא הגדרה אופציונלית של שרת Proxy API, אבל בפועל לא מומלץ להשתמש בהפעלה ישירה דרך ProxyEndpoint.
לדוגמה, ה-RoutRule הבא מבצע קריאת HTTP אל
http://api.mycompany.com/v2
.
<RouteRule name="default"> <URL>http://api.mycompany.com/v2</URL> </RouteRule>
מסלולים מותנים
ניתן לשרשר את RouteRules כדי לתמוך בניתוב דינמי בזמן ריצה. בקשות נכנסות יכולות להיות מנותבות לתצורות עם שם יעד ייעודי, ישירות לכתובות URL או לשילוב של שתי השיטות, על סמך כותרות HTTP, תוכן של הודעה, פרמטרים של שאילתה או מידע הקשרי, כמו השעה ביום, הלוקאל וכו'.
RouteRules מותנים פועלים כמו הצהרות מותנות אחרות ב-Apigee Edge. מידע נוסף זמין בהפניות לתנאים ובחומר העזר בנושא משתנים.
לדוגמה, השילוב הבא של RouteRule מעריך את הבקשה הנכנסת כדי לאמת את הערך של כותרת HTTP. אם הערך של כותרת ה-HTTP routeTo
הוא TargetEndpoint1
, הבקשה תועבר לנקודת היעד (endpoint) ששמה 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
אפשר להגדיר נתיב RonullRule לתמיכה בתרחישים שבהם לא צריך להעביר את הודעת הבקשה אל TargetEndpoint. האפשרות הזו שימושית כשבשרת ה-proxy מתבצעת כל העיבוד הנדרש. לדוגמה, שימוש ב-JavaScript כדי להתקשר לשירות חיצוני או באחזור נתונים מחיפוש מידע אל המפתח/ערך של שירותי ה-API.
לדוגמה, הקוד הבא מגדיר נתיב null:
<RouteRule name="GoNowhere"/>
נתיבי null מותנים יכולים להיות שימושיים. בדוגמה הבאה, נתיב null מוגדר לביצוע כשכותרת HTTP request.header.X-DoNothing
מכילה ערך שאינו null
.
<RouteRule name="DoNothingOnDemand"> <Condition>request.header.X-DoNothing != null</Condition> </RouteRule>
חשוב לזכור שניתן לשרשר את RouteRules, כך שנתיב null מותנה יהיה בדרך כלל רכיב אחד של קבוצת RouteRules שמיועד לתמוך בניתוב מותנה.
שימוש מעשי בנתיב null מותנה יכול לשמש כשמירה במטמון. באמצעות הערך של המשתנה שמוגדר במדיניות המטמון, אפשר להגדיר שרת proxy ל-API שיבצע את נתיב ה-null כשרשומה תוצג מהמטמון.
<RouteRule name="DoNothingUnlessTheCacheIsStale"> <Condition>lookupcache.LookupCache-1.cachehit is true</Condition> </RouteRule>
נקודת קצה (endpoint)
TargetEndpoint הוא המקבילה היוצאת של ProxyEndpoint. TargetEndpoint פועל כלקוח לשירות לקצה עורפי או ל-API – הוא שולח בקשות ומקבל תשובות.
שרת proxy ל-API לא חייב לכלול TargetEndpoints. אפשר להגדיר את ProxyEndpoints כך שיקרא כתובות URL ישירות. שרת proxy ל-API ללא TargetEndpoints מכיל בדרך כלל שרת proxy שמפעיל ישירות שירות לקצה עורפי או מוגדר לבצע קריאה לשירות באמצעות Java או JavaScript.
הגדרות אישיות של נקודת היעד
/targets/default.xml
TargetEndpoint מגדיר את החיבור יוצא מ-Apigee Edge לשירות או למשאב אחרים.
הנה דוגמה להגדרה של יעד EndEnd:
<TargetEndpoint name="default"> <PreFlow/> <Flows/> <PostFlow/> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <SSLInfo/> </HTTPTargetConnection> <FaultRules/> <DefaultFaultRule/> <ScriptTarget/> <LocalTargetConnection/> </TargetEndpoint>
רכיבים של תצורת נקודת קצה (endpoint)
אפשר להשתמש ביעד באמצעות קריאה ליעד באחת מהדרכים הבאות:
- HTTPTargetConnection עבור קריאות ל-HTTP(S)
- LocalDestinationConnection עבור שרשור של שרת proxy מקומי
- Target Script עבור קריאות לסקריפט Node.js שמתארח ב-Edge
צריך להגדיר רק אחת מהן ב-TargetEndpoint.
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
TargetEndpoint |
|||
name |
השם של נקודת היעד של EndEnd, שחייב להיות ייחודי בהגדרות של ה-proxy של ה-API. ב-ProxyEndpoint RouteRule נעשה שימוש בשם של ה-TargetEndPoint, כדי להפנות בקשות לעיבוד של עיבוד יוצא. התווים המותרים בשם
מוגבלים ל-A-Za-z0-9._\-$ % הבאים. |
לא רלוונטי | כן |
PreFlow |
מגדיר את המדיניות בתהליך ה-PreFlow של בקשה או תגובה. | לא רלוונטי | כן |
Flows |
מגדיר את כללי המדיניות בהליכים המותנים של בקשה או תגובה.
|
לא רלוונטי | כן |
PostFlow |
מגדיר את המדיניות בתהליך ה-PostFlow של בקשה או תגובה.
|
לא רלוונטי | כן |
HTTPTargetConnection |
עם רכיבי הצאצא שלו, מצוין טווח ההגעה של הקצה העורפי באמצעות HTTP. אם משתמשים ב-HTTPTargetConnection, לא צריך להגדיר סוגים אחרים של חיבורי יעד (ScriptTarget או LocalTargetConnection). |
||
URL |
המדיניות הזו מגדירה את כתובת הרשת של השירות לקצה העורפי שאליו מעבירה נקודת הקצה (endpoint) את ההודעות. | לא רלוונטי | לא |
LoadBalancer |
מוגדרת לפחות הגדרה אחת בשם TargetServer. אפשר להשתמש בהגדרות עם שם של שרת Server בשביל איזון עומסים עם הגדרה של 2 חיבורים או יותר של נקודות קצה (endpoint). אפשר גם להשתמש ב-TargetServers כדי לפענח הגדרות של שרת proxy ל-API מכתובות URL של נקודות קצה (endpoint) בשירותי בטון. למידע נוסף, קראו את המאמר איזון עומסים בין שרתים לקצה העורפי. |
לא רלוונטי | לא |
Properties |
אפשר לקבוע קבוצה של הגדרות אופציונליות של HTTP בתור מאפיינים של
<TargetEndpoint> . |
לא רלוונטי | לא |
SSLInfo |
אפשר לבחור הגדרות TLS/SSL ב-TargetEndpoint כדי לשלוט בחיבור TLS/SSL בין שרת ה-API ל-API לבין שירות היעד. למידע נוסף, ניתן לעיין במאמר TLS/SSL Target Endpoint Configuration. | לא רלוונטי | לא |
LocalTargetConnection |
ברכיבי הצאצא שלו, מצוין שהמשאב יגיע אליו באופן מקומי, תוך עקיפת מאפייני הרשת כגון איזון עומסים ומעבדי הודעות.
כדי לציין את משאב היעד, יש לכלול את רכיב הצאצא Proxy API (עם רכיב ProxyEndpoint) או את רכיב הצאצא Path. מידע נוסף זמין במאמר שרשור של שרתי proxy API. אם משתמשים ב-LocalTargetConnection, אין להגדיר סוגים אחרים של חיבורי יעד (HTTPTargetConnection או ScriptTarget). |
||
APIProxy |
ההגדרה קובעת את השם של שרת proxy ל-API שישמש כיעד לבקשות. שרת ה-proxy של היעד צריך להיות באותו ארגון ובאותה סביבה שבה פועלות בקשות ה-proxy. זוהי חלופה לשימוש ברכיב הנתיב. | לא רלוונטי | לא |
ProxyEndpoint |
משמש עם APIProxy כדי לציין את השם של ProxyEndpoint של שרת ה-proxy. | לא רלוונטי | לא |
Path |
המדיניות מציינת את נתיב נקודת הקצה של שרת proxy ל-API שישמש כיעד לבקשות. שרת ה-proxy המיועד צריך להיות באותו ארגון ובאותה סביבה כמו אלו של בקשות ה-proxy הנשלחות. זוהי חלופה לשימוש ב-APIProxy. | לא רלוונטי | לא |
FaultRules |
מגדירה איך נקודת הקצה (endpoint) מגיבה לשגיאה. כלל כשל מציין שני פריטים:
עיינו בקטע טיפול בשגיאות. |
לא רלוונטי | לא |
DefaultFaultRule |
טיפול בשגיאות (מערכת, תחבורה, העברת הודעות או מדיניות) שלא מטופלות באופן מפורש על ידי FaultRule אחר. עיינו בקטע טיפול בשגיאות. |
לא רלוונטי | לא |
ScriptTarget |
|||
ResourceURL |
המדיניות מגדירה את סוג המשאב (צומת) ואת השם של הסקריפט הראשי ב-Node.js שמטמיע פונקציונליות של TargetEndpoint.
יש לכלול את הסקריפט בקובצי המשאבים של שרת ה-API של ה-API. למידע נוסף, ראו הוספת Node.js לשרת proxy קיים של API. אם משתמשים ב-ScriptTarget, אין להגדיר סוגים אחרים של חיבורי יעד (HTTPHTTPConnection או LocalTargetConnection). |
לא רלוונטי | כן |
EnvironmentVariable |
אם רוצים, אפשר להעביר משתני סביבה לסקריפט הראשי של Node.js. למידע נוסף, ניתן לעיין בתמיכה ב-Edge Edge למודולים של Node.js. |
לא רלוונטי | לא |
Arguments |
אם רוצים, אפשר להעביר ארגומנטים לסקריפט הראשי של Node.js. למידע נוסף, ניתן לעיין בתמיכה ב-Edge Edge למודולים של Node.js. |
לא רלוונטי | לא |
תצורת נקודת יעד של TLS/SSL
לרוב, TargetEndpoints צריך לנהל חיבורי HTTPS עם תשתית הטרוגנית (הקצה העורפי). לכן יש תמיכה בכמה הגדרות תצורה של TLS/SSL.
רכיבי תצורה של TLS/SSL TargetEndpoint
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
SSLInfo |
|||
Enabled |
התנאי מציין אם TLS/SSL מופעל לנקודת הקצה.
ערך ברירת המחדל הוא true אם <URL> מציין את פרוטוקול HTTPS, ו-false אם הערך <URL> מציין HTTP. |
הערך הוא תקין אם הפרמטר <URL> מציין HTTPS |
לא |
TrustStore |
מאגר מפתחות שמכיל אישורי שרת מהימנים. | לא רלוונטי | לא |
ClientAuthEnabled |
הגדרה שמפעילה אימות של לקוח יוצא (TLS/TLS דו-כיווני) | false | לא |
KeyStore |
מאגר מפתחות שמכיל מפתחות פרטיים שמשמשים לאימות של לקוחות יוצאים | לא רלוונטי | כן (אם ClientAuthEnabled נכון) |
KeyAlias |
הכינוי של המפתח הפרטי המשמש לאימות של לקוח יוצא | לא רלוונטי | כן (אם ClientAuthEnabled נכון) |
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. כדי להגביל את הפרוטוקולים, מוסיפים את האלמנטים הבאים ורושמים את הפרוטוקולים הנתמכים: <Protocols> <Protocol>TLSv1.1</Protocol> <Protocol>TLSv1.2</Protocol> </Protocols> |
לא רלוונטי | לא |
יעד סופי לדוגמה עם אימות של לקוח יוצא
<TargetEndpoint name="default"> <HttpTargetConnection> <URL>https://myservice.com</URL> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>myKeystore</KeyStore> <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> </SSLInfo> </HttpTargetConnection> </TargetEndpoint>
הוראות מפורטות זמינות במאמר הגדרת TLS (אבטחת שכבת התעבורה) מקצה הקצה (Cloud וענן פרטי).
שימוש במשתני זרימה כדי להגדיר ערכי TLS/SSL באופן דינמי
ניתן גם להגדיר פרטי TLS/SSL באופן דינמי כדי לתמוך בדרישות זמן ריצה גמישות. לדוגמה, אם שרת ה-proxy מתחבר לשני יעדים שעשויים להיות שונים (יעד בדיקה ויעד ייצור), אפשר להגדיר את שרת ה-API של Google פרוגרמטי לזהות לאיזו סביבה הוא מתקשר ולהגדיר באופן דינמי הפניות למאגר המפתחות ולמאגר האמון המתאים. המאמר הבא של קהילת Apigee מסביר את התרחיש הזה בפירוט רב יותר ומספק דוגמאות של שרת proxy ל-API: https://community.apigee.com/articles/21424/Dynamic-sslinfo-for-targetendpoint-using-variable.html.
בדוגמה הבאה של אופן ההגדרה של התג <SSLInfo>
בתצורה של TargetEndpoint, אפשר להזין את הערכים בזמן הריצה, למשל באמצעות יתרונות מרכזיים של Java, מדיניות JavaScript או מדיניות הקצאת הודעות. משתמשים במשתני הודעות שמכילים את הערכים שרוצים להגדיר.
מותר להשתמש במשתנים רק ברכיבים הבאים.
<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 באופן דינמי
כשמגדירים נקודת קצה (endpoint) שמשתמשת ב-HTTPS, צריך להביא בחשבון את תפוגת התוקף של אישור ה-TLS/SSL, או לשנות את הגדרת המערכת כדי לעדכן את האישור. בהתקנה של Edge לענן פרטי, כשמגדירים TLS/SSL באמצעות ערכים סטטיים או באמצעות משתני זרימה, צריך להפעיל מחדש את מעבדי ההודעות.
למידע נוסף, קראו את המאמר עדכון אישור TLS.
עם זאת, אפשר להגדיר את נקודת הקצה (endpoint) לשימוש בהפניה למאגר המפתחות או ל-Truststore. היתרון בשימוש בקובץ עזר הוא שאתם יכולים לעדכן את קובץ העזר כך שיפנה למאגר מפתחות אחר או ל-Trust Store, כדי לעדכן את אישור ה-TLS/SSL בלי שתצטרכו להפעיל מחדש את מעבדי ההודעות.
לדוגמה, בהמשך מוצגת נקודת קצה (endpoint) שמשתמשת בהפניה למאגר המפתחות:
<SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>false</ClientAuthEnabled> <KeyStore>ref://keystoreref</KeyStore> <KeyAlias>myKeyAlias</KeyAlias> </SSLInfo>
משתמשים בקריאה הבאה ל-POST API כדי ליצור את קובץ העזר בשם keystoreref:
curl -X POST -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \ -d '<ResourceReference name="keystoreref"> <Refers>myTestKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password
קובץ העזר מציין את שם מאגר המפתחות ואת סוגו.
כדי להציג את קובץ העזר, תוכלו להשתמש בקריאה הבאה ל-GET API:
curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
כדי לשנות את ההפניה כך שתוביל לחנות מפתחות אחרת, ובכך להבטיח שלכינוי החלופי יהיה שם זהה, אפשר להשתמש בקריאה הבאה ל-PUT:
curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \ -d '<ResourceReference name="keystoreref"> <Refers>myNewKeystore</Refers> <ResourceType>KeyStore</ResourceType> </ResourceReference>' -u email:password
TargetEndpoint עם איזון עומסים ביעד
TargetEndpoints תומך באיזון עומסים בין שרתי שמות עם שמות מרובים, באמצעות שלושה אלגוריתמים לאיזון עומסים.
להוראות מפורטות, ראו איזון עומסים בין שרתים עורפיים.
כללי המדיניות
הספרייה /policies
בשרת proxy של API מכילה את כל כללי המדיניות שאפשר לצרף
לזרימות ב-Proxy של ה-API.
אלמנטים של הגדרת מדיניות
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
Policy |
|||
name |
השם הפנימי של המדיניות. מספר התווים שאפשר להשתמש בהם בשם מוגבל: אפשר להשתמש ברכיב |
לא רלוונטי | כן |
enabled |
יש להגדיר את המדיניות מגדירים את |
true | לא |
continueOnError |
יש להגדיר את הערך המדיניות מקבלת את הערך |
false | לא |
async |
הערה: המאפיין הזה לא גורם למדיניות לפעול באופן אסינכרוני.
ברוב המקרים, משאירים את ברירת המחדל אם המדיניות מוגדרת כ- במאמר מודל אובייקט JavaScript מוסבר איך להשתמש בהתנהגות אסינכרונית בשרתי proxy של API. |
false | לא |
קובץ מצורף למדיניות
בתמונה הבאה מוצג רצף הביצוע של שרתי proxy ב-API:
כפי שמוצג למעלה:
כללי המדיניות מצורפים כשלבי עיבוד אל זרימת נתונים. שם המדיניות משמש להפניה לאכיפה של המדיניות כשלב עיבוד. הפורמט של קובץ מצורף למדיניות הוא:
<Step><Name>MyPolicy</Name></Step>
כללי המדיניות נאכפים לפי הסדר שבו הם מצורפים לזרימת נתונים. לדוגמה:
<Step><Name>FirstPolicy</Name></Step> <Step><Name>SecondPolicy</Name></Step>
רכיבי קובץ תצורה של מדיניות
שם | תיאור | ברירת המחדל | חובה? |
---|---|---|---|
Step |
|||
Name |
שם המדיניות להרצה בהגדרת השלב הזה. | לא רלוונטי | כן |
Condition |
הצהרה מותנית שקובעת אם המדיניות נאכפת או לא. אם למדיניות יש תנאי משויך, היא תיושם רק אם ההצהרה המותנית מוערכת כ-TRUE. | לא רלוונטי | לא |
פרחים
ProxyEndpoint ו-TargetEndpoint מגדירים צינור עיבוד נתונים לעיבוד של בקשות ושל תגובות. צינור עיבוד נתונים מורכב מזרימה של בקשות ומתהליך תגובה. כל זרימת בקשה ותהליך חלוקת משנה מחולקים ל-PreFlow, זרימה 'מותנית' אחת או יותר ו-'name', ו-PostFlow.
- PreFlow: תמיד פועל. מופעלת לפני כל מעבר מותנה.
- PostFlow: תמיד מתבצעת. הפעולה מתבצעת לאחר כל מעבר מותנה.
בנוסף, ניתן להוסיף PostClientFlow ל-ProxyEndpoint, אשר מופעל לאחר שהתגובה מוחזרת לאפליקציית הלקוח המבקשת. ניתן לצרף לתהליך זה רק את המדיניות של MessageLogging ואת תוסף הרישום ביומן של Stackdriver. PostClientFlow מפחיתה את זמן האחזור של שרת ה-API של API והופכת את המידע לזמין
לרישום ביומן שלא יחושב עד לאחר החזרה של התשובה ללקוח, כמו
client.sent.start.timestamp
ו-client.sent.end.timestamp
.התהליך משמש
בעיקר למדידת מרווח הזמן בין חותמות הזמן של ההתחלה והסיום של הודעת
התגובה.
לצפייה בסרטון הדרכה מהיר
סרטון: מומלץ לצפות בסרטון הקצר הזה בנושא השימוש ברישום ביומן ב-PostClientFlow.
דוגמה ל-PostClientFlow עם מדיניות לרישום הודעות.
... <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow> <Request/> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ...
צינור עיבוד ה-proxy של ה-API מפעיל את הזרימה ברצף הבא:
צינור עיבוד נתונים:
- בקשת מראש של שרת Proxy
- זרימה מותנית של בקשת שרת Proxy (אופציונלי)
- בקשת Proxy לאחר זרימה
- בקשת יעד מוקדמת ל-FFLO
- יעדים מותנים לבקשת יעד (אופציונלי)
- בקשת יעד להעברת דואר
צינור עיבוד תגובה:
- יעד מראש של תגובת יעד
- נוהלי יעד של תגובה לתגובה (אופציונלי)
- יעד לתגובה בסוף נתיב
- תגובה מראש של שרת proxy
- הליכים מותנים של תגובות לשרת proxy (אופציונלי)
- תגובה חלופית לשרת proxy לשליחת תגובות לשרת proxy
- תגובה של PostClientFlow (אופציונלי)
יש להגדיר רק תהליכי עבודה עם קובצי מדיניות מצורפים, בתצורות ProxyEndpoint או TargetEndpoint. יש לציין את השדות PreFlow ו-PostFlow רק בהגדרות של ProxyEndpoint או ב-TargetEndpoint, כשצריך לאכוף מדיניות במהלך העיבוד של PreFlow או של PostFlow.
בניגוד לתהליכים מותנים, הסדר של הרכיבים PreFlow ו-PostFlow לא חשוב. שרת ה-API של API יבצע תמיד כל פעולה בנקודה המתאימה בצינור עיבוד הנתונים, בלי קשר למקום שבו הם מופיעים בתצורה של נקודת הקצה.
זרימה מותנית
שרתי ProxyEndpoints ו-TargetEndpoints תומכים במספר בלתי מוגבל של תהליכים מותנים (שנקראים גם 'זרימות בעלות שם').
שרת ה-proxy של ה-API בודק את התנאי שצוין בתהליך המותנה, ואם התנאי מתקיים, שלבי העיבוד בזרימה המותנית מבוצעים על ידי שרת ה-API של ה-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 |
צינור עיבוד נתונים של בקשות או תגובות המוגדר על ידי ProxyEndpoint או TargetEndpoint | ||
Name |
השם הייחודי של מקור הנתונים. | לא רלוונטי | כן |
Condition |
הצהרה מותנית שיש לה הערכה על משתנים או יותר כדי להעריך אותם כ-true או false. כל התהליכים, מלבד הסוגים המוגדרים מראש של PreFlow ו-PostFlow, חייבים להגדיר תנאי לביצוע. | לא רלוונטי | כן |
Request |
צינור עיבוד הנתונים לעיבוד עיבוד בקשות | לא רלוונטי | לא |
Response |
צינור עיבוד הנתונים לעיבוד עיבוד של הודעות תגובה | לא רלוונטי | לא |
עיבוד שלבים
הסדר הרגולרי של זרימה מותנית נאכף על ידי Apigee Edge. זרימה מותנית
מופעלת מלמעלה למטה. הזרימה המותנית הראשונה עם תנאי שמבוצעת ל-true
מתבצעת, ורק זרימה מותנית אחת מופעלת.
לדוגמה, בהגדרה הזו של 'זרימה', כל בקשה נכנסת שלא כוללת את סיומת הנתיב /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) הם סקריפטים, קוד וטרנספורמציות של XSL שאפשר לצרף לזרימות נתונים באמצעות מדיניות. הנכסים האלה מופיעים בקטע "Scripts" בעורך ה-API של ה-API בממשק המשתמש לניהול.
במאמר קובצי משאבים תוכלו לראות את סוגי המשאבים הנתמכים.
אפשר לאחסן משאבים בשרת proxy של API, בסביבה מסוימת או בארגון. בכל אחת מהשיטות, השם של המשאב מופיע במדיניות. שירותי ה-API משנים את השם על ידי מעבר משרת proxy של הממשק לסביבה של הארגון ברמת הארגון.
כל סביבה שאוחסנה ברמת הארגון יכולה להופיע בכללי המדיניות בכל סביבה. משאב המאוחסן ברמת הסביבה ניתן לאחזור על ידי מדיניות בתוך הסביבה הזו. משאב המאוחסן ברמת שרת ה-API של ה-API יכול להפנות רק ל'מדיניות' עבור אותו שרת proxy ב-API.