אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.
כל מודל תכנות של אפליקציה כולל דרך לשליטה בזרימת העיבוד. בשרת proxy של API, זה מתבצע עם התהליכים. בתהליכים אפשר להוסיף לוגיקה, הצהרות תנאים, טיפול בשגיאות וכו'. אתם משתמשים בזרימות כדי לקבוע מה יקרה ומתי.
תהליכים הם שלבים רצופים לאורך תהליך העיבוד של בקשות ה-API. כשמוסיפים לוגיקת שרת proxy, כמו אימות של מפתח API, מוסיפים את הלוגיקה כשלב ברצף שצוין באמצעות זרימה. כשמגדירים תנאי כדי לקבוע אם ומתי לוגיקה מופעלת, אפשר להוסיף את התנאי לזרימה.
הדוגמה הבאה של תצורת זרימה מגדירה זרימה שבה המדיניות ValidAPIKey מופעלת אם נתיב הבקשה הנכנס מסתיים ב-/
ופעל ה-HTTP של הבקשה הוא GET.
<Flow name="Get Food Carts"> <Description>Get Food Carts</Description> <Request> <Step> <Name>Verify-API-Key</Name> </Step> </Request> <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition> </Flow>
הערך Verify-API-Key
ברכיב <Name>
של התהליך משמש להגדרת מדיניות שהוגדרה במקום אחר בשרת ה-proxy באמצעות XML, כמו בדוגמה הבאה:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key"> <DisplayName>Verify API Key</DisplayName> <Properties/> <APIKey ref="request.header.x-api-key"/> </VerifyAPIKey>
תכנון רצף של ביצוע תהליך
המבנה שלכם משתנה כדי שתוכלו לבצע לוגיקה ברצף הנכון לאורך נתיב העיבוד.
כשמחליטים איפה להוסיף לוגיקה, קודם צריך לבחור אם להוסיף אותו לנקודת קצה (endpoint) או לנקודת קצה (endpoint). שרת proxy של API מחלק את הקוד בין קוד שיש לו אינטראקציה עם הלקוח של נקודת הקצה (Proxy) לבין קוד אופציונלי שמקיים אינטראקציה עם היעד של הקצה העורפי של שרת ה-proxy, אם יש כזה.
שתי נקודות הקצה מכילות זרימה, כפי שמתואר כאן:
סוג נקודת קצה (endpoint) | תיאור | תהליכי עבודה נתמכים |
---|---|---|
נקודת קצה של Proxy | מכיל את זרימות ה-API של ה-API הקרובות ביותר ללקוח. מספק מקומות לוגיים שיוכלו לפעול לפי בקשה מהלקוח, ולבסוף להגיב ללקוח. | PreFlow, תנאים מותנים, PostFlow, PostClientFlow |
נקודת קצה (endpoint) | מכיל את תהליכי ה-proxy של ממשק ה-API הקרובים ביותר למשאב הקצה העורפי. הפלטפורמה מספקת מקומות לוגיים להכנה של הבקשה למשאב בקצה העורפי, ולטיפול בה. | PreFlow, תנאים מותנים, PostFlow |
הגדרת הזרימה באמצעות XML המציינת מה צריך לקרות ובאיזה סדר. באיור הבא מוצג האופן שבו סדר הזרימה עוקב אחרי נקודת קצה (endpoint) ונקודת קצה (endpoint) של יעד:
נקודת הקצה של שרת ה-proxy ונקודת הקצה של היעד מכילים כל אחד מהזרימה, שניתן לארגן בסדר הבא:
מיקום | סוג הזרימה | תיאור |
---|---|---|
1 | קדם-זרימה |
כדאי להשתמש באפשרות הזו כשצריך לוודא שקוד מסוים מופעל לפני שמתרחש משהו אחר. אם ה-PreFlow היא בנקודת הקצה של היעד, היא מתבצעת לאחר ה-PostFlow של נקודת הקצה של שרת ה-proxy. |
2 | זרימה מותנית |
המקום ללוגיקה מותנית. פועל אחרי ה-PreFlow ולפני ה-PostFlow.
רק זרימה מותנית אחת מופעלת לכל פלח - הזרימה הראשונה
שתנאיה מוערך כ-true. כלומר, אפשר לבצע תהליך מותנה אחד כחלק מכל:
|
3 | פוסט זרימה |
מקום טוב לרישום נתונים, לשליחת התראות שמשהו קרה בזמן עיבוד הבקשה וכו'. הפעולה מתבצעת לאחר תהליכי הזרימה המותנים והפעלת PreFlow. אם ה-PostFlow נמצאת בנקודת קצה של שרת proxy, וקיימת נקודת קצה (endpoint), נקודת הקצה של שרת ה-proxy היא מופעלת לפני נקודת הקצה של היעד. |
4 | PostClientFlow (תהליך proxy בלבד) | תהליך לרישום הודעות אחרי החזרה של תשובה ללקוח. |
להפעיל את הקוד קודם באמצעות PreFlow
PreFlow היא פונקציה שימושית כשצריך לוודא שקוד מסוים מופעל לפני שמתרחש משהו אחר.
בנקודת קצה של שרת proxy, PreFlow היא מקום מצוין לקוד שמאמת לקוח ומגביל את התנועה מלקוחות. בנקודת קצה של יעד, שבה היא מתחילה להתכונן לשליחת בקשה ליעד עורפי, PreFlow היא מתאימה לשלבים הראשונים בהכנה לשליחת הבקשה.
לדוגמה, בדרך כלל לא תרצו לתת שירות ללקוח שלא חרג מהמכסה שלו. כדי לעמוד בדרישות האלה, יש להוסיף את המדיניות בנושא אבטחה ומכסות לפלחים ב-PreFlow. כך לא צריך לחשוש שתנאי התנאי לא יחושב. כללי המדיניות בתהליך הזה תמיד יחולו לפני שיבוצע עיבוד אחר.
בדוגמה הבאה, המדיניות של SpikeArrest ו-Quota מתבצעות לפני העיבוד של מעברים לתהליכים מותנים.
<PreFlow name="MyPreFlow"> <Request> <Step> <Name>Spike-Arrest</Name> </Step> <Step> <Name>Quota</Name> </Step> </Request> <Response/> </PreFlow>
ביצוע של קוד מותנה באמצעות תהליך מותנה
בין PreFlow לבין PostFlow, יכולים להיות לכם תהליכים לביצוע באופן מותנה. כך אפשר להגדיר רצפים הגיוניים רבים, אבל להפעיל רק אחד מהם על סמך המצב של שרת ה-proxy. תהליך מותנה הוא אופציונלי, אם ניתן להפעיל את כל הלוגיקה ב-PreFlow או ב-PostFlow. לא נדרשים תנאים (במילים אחרות, רק נתיב אחד מנקודת הקצה נתמך).
כל תהליך מציין תנאי שבודק אם קיימים ערכי מצב שונים. בפועל, ההסתעפות מבוססת על תנאים. לדוגמה, ייתכן שתרצו להמיר XML ל-JSON רק כשהאפליקציה המבקשת פועלת במכשיר נייד.
כאן, מגבלות האילוץ נאכפות רק אם הבקשה היא בקשה של GET
עם תבנית URI של /issue/**
(/issue/, עם כל דבר ב-URI אחרי הקו הנטוי האחרון).
<Flow name="MyFlow"> <Description/> <Request> <Step> <Name>Quota</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition> </Flow>
אתם משתמשים במשתני זרימה כדי לציין תנאים. למידע נוסף על השימוש במשתנים בתנאים, אפשר לעיין בקטע תנאים עם משתני זרימה.
דוגמאות לשימוש בהתאמה לדפוס בתנאים אפשר למצוא במאמר התאמת תבניות.
הרצה של קוד אחרי הלוגיקה של PostFlow
PostFlow היא מקום מצוין לביצוע פעולות לאחר לוגיקת נקודת הקצה (endpoint) שלכם ולפני שעיבוד נקודת הקצה מסתיים. העברה של PostFlow מתבצעת לאחר הזרימה של התנאי וה-PreFlow.
פרסום פוסט ב-PostFlow הוא מקום טוב לרישום נתונים מסוימים, לשליחת התראות על כך שמשהו קרה, לשינוי פורמט הודעת התגובה וכו'.
בדוגמה הבאה, מדיניות AssignMessage שנקראת SetResponseHeaders מגדירה כותרות של הודעת התגובה לפני שמערכת Apigee Edge שולחת את התגובה בחזרה ללקוח.
<PostFlow> <Response> <Step> <Name>SetResponseHeaders</Name> </Step> </Response> </PostFlow>
הרצה של קוד אחרי שהלקוח מקבל את תגובת ה-proxy באמצעות PostClientFlow
PostClientFlow יכולה לכלול את סעיפי המדיניות הבאים:
- המדיניות בנושא תוספי יתרונות מרכזיים
- מדיניות 'יתרונות מרכזיים'*
- המדיניות בנושא MessageLogging
- המדיניות בנושא יתרונות מרכזיים של שירות
* המדיניות 'יתרונות מרכזיים של תהליך' יכולה להפעיל רק תהליכי שיתוף שעומדים בעצמם בקריטריונים לפרסום ב-PostClientFlow (כלומר, מכילים רק כללי מדיניות תואמים).
אם כוללים דומיין, השליחה של PostClientFlow תהיה התהליך האחרון לביצוע, שתתבצע לאחר שליחת תגובה ללקוח.
שליחה של PostClientFlow היא שיטה טובה לרישום ביומן. אפשר גם לרשום את חותמות הזמן של ההתחלה והסיום של הודעת התשובה.
דוגמה ל-PostClientFlow עם מדיניות MessageLogging צורפה.
... <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow> <Request/> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ...
סרטון: מומלץ לצפות בסרטון הקצר הזה שמראה איך ליצור PostClientFlow באמצעות המדיניות MessageLogging מהסדרה ארבע דקות למפתחים (4MV4D).
מידע נוסף זמין בדפים הבאים:
הוספת לוגיקה לתזרימים
כאשר מוסיפים לוגיקה לשרת ה-proxy, אפשר לעשות זאת על ידי הוספת כללי מדיניות לתהליכים של שרת ה-proxy. בדיוק כמו שזרימות מתבצעות ברצף (PreFlow ואז Flow ו-PostFlow, כפי שמתואר בנושא הזה), כך התוכן של רצף מתבצע ברצף.
ההגדרה הבאה של תהליך הזרימה מציינת שלושה כללי מדיניות (שנקבעו במקום אחר בקובצי XML משלהם). המדיניות שצוינה ב-Verify-API-Key
מופעלת לפני המדיניות שצוינה ב-Remove-API-Key
. לאחר המדיניות הזו, המדיניות מיוצגת על ידי Quota
.
<Flow name="Get Food Cart Menus"> <Description>Get Food Cart Menus</Description> <Request> <Step> <Name>Verify-API-Key</Name> </Step> <Step> <Name>Remove-API-Key</Name> </Step> <Step> <Name>Quota</Name> </Step> </Request> <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition> </Flow>
מסוף Apigee Edge מציג את רצף המדיניות הזה כשורה של סמלים, כאשר כל סמל מייצג את המדיניות.
תהליכי ניפוי באגים
הכלי Apigee Edge Trace מספק דרך גרפית לראות איך הלוגיקה של שרת ה-proxy של ה-API שלך מתבצעת לאחר בקשה. הכלי ממחיש את העיבוד בין הבקשה לתגובה. הוא לא ממחיש באופן ספציפי את ההפרדה בין PreFlow, זרימה מותנית ו-PostFlow.
למידע נוסף על מעקב אחר שרתי proxy, ניתן לעיין בשימוש בכלי המעקב.
טיפול בשגיאות בתהליך
אפשר להגדיל שגיאות ממקומות שונים בשרת proxy של API, כולל מזרימות.
בדוגמה הבאה אפשר לראות את הקוד מ-PreFlow בנקודת קצה של יעד. כלומר, הקוד הוא זה שמתבצע מיד עם קבלת התשובה מהיעד בקצה העורפי. בדוגמה הזו, מוצגת תקלה אם התגובה מיעד היא לא 200 (הצלחה).
<PreFlow name="PreFlow"> <Response> <Step> <Name>RaiseFault</Name> <Condition>(response.status.code GreaterThan "200")</Condition> </Step> </Response> </PreFlow>
מידע נוסף על טיפול בשגיאות זמין במאמר טיפול בשגיאות.