שליטה באופן שבו שרת proxy פועל באמצעות זרימה

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

בדוגמה הבאה להגדרת זרימה מוגדרת זרימה שבה המדיניות VerifyAPIKey מופעלת אם נתיב הבקשה הנכנסת מסתיים ב-/ ופועל הפועל 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>

תכנון רצף הביצוע של התהליך

אתם יכולים לבנות את התהליכים כך שהלוגיקה תפעל ברצף הנכון לאורך נתיב העיבוד.

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

שתי נקודות הקצה מכילות תהליכים, כפי שמתואר כאן:

אתם מגדירים את התהליך באמצעות קובץ XML שמציין מה צריך לקרות ובאיזה סדר. האיור הבא מראה איך רצפי הפעולות מסודרים באופן עוקב בנקודת קצה של שרת proxy ובנקודת קצה של יעד:

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

PostFlow הוא מקום טוב לרשום נתונים מסוימים, לשלוח התראה על אירוע מסוים, לשנות את פורמט הודעת התשובה וכו'.

בדוגמה הבאה, מדיניות AssignMessage בשם SetResponseHeaders מגדירה כותרות של הודעת התגובה לפני ש-Apigee Edge שולח את התגובה בחזרה ללקוח.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

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

‫PostClientFlow יכול לכלול את כללי המדיניות הבאים:

• המדיניות בנושא ExtensionCallout
• מדיניות FlowCallout^*
• מדיניות MessageLogging
• מדיניות ServiceCallout

‫^* מדיניות FlowCallout יכולה להפעיל רק תהליכים משותפים שעומדים בקריטריונים של PostClientFlow (כלומר, מכילים רק מדיניות תואמת).

אם כוללים כזה, PostClientFlow יהיה הרצף האחרון שיבוצע, אחרי שליחת התגובה ללקוח.

השימוש ב-PostClientFlow מתאים לרישום סופי ביומן. בנוסף, אפשר לרשום ביומן את חותמות הזמן של ההתחלה והסיום של הודעת התגובה.

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

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

מידע נוסף זמין בדפים הבאים:

• הפניית הגדרות של proxy ל-API
• Tutorial : Apigee Edge - Post Client Flow community article

הוספת לוגיקה לתהליכים

כשמוסיפים לוגיקה לשרת ה-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 זמין במאמר שימוש בכלי Trace.

טיפול בשגיאות בתהליכים

אפשר להעלות תקלות ממקומות שונים ב-proxy ל-API, כולל מ-Flows.

בדוגמה הבאה מוצג קטע תגובה מ-PreFlow בנקודת קצה של יעד – במילים אחרות, זהו הקוד שמופעל מיד עם קבלת התגובה מיעד בקצה העורפי. בדוגמה, אם התגובה מהיעד היא לא 200 (הצלחה), מופעלת שגיאה.

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

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