שליטה בשרתי proxy ל-API באמצעות רכיבי Flow

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

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

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

הזרימות הן שלבים עוקבים לאורך נתיב העיבוד של בקשת ה-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 או לנקודת קצה של יעד. קוד ה-API proxy מחולק לקוד שמתקשר עם הלקוח של ה-proxy (נקודת הקצה של ה-proxy) ולקוד אופציונלי שמתקשר עם יעד הקצה העורפי של ה-proxy, אם יש כזה (נקודת הקצה של היעד).

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

סוג נקודת הקצה	תיאור	‫Flows נתמך
ProxyEndpoint	מכיל את זרימות ה-proxy ל-API שהכי קרובות ללקוח. מספק מקומות ללוגיקה לפעול קודם על הבקשה מהלקוח, ואז אחרון על התגובה ללקוח.	PreFlow, תהליכים מותנים, PostFlow, ‏ PostClientFlow
TargetEndpoint	מכיל את התהליכים של שרת ה-proxy ל-API שהכי קרובים למשאב בקצה העורפי. מספק מקומות ללוגיקה כדי להכין בקשה למשאב עורפי, ואז לטפל בתגובה ממנו.	‫PreFlow, תהליכים מותנים, PostFlow

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

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

מקום	סוג התהליך	תיאור
1	PreFlow	השיטה הזו שימושית כשרוצים לוודא שקטע קוד מסוים יופעל לפני כל פעולה אחרת. אם PreFlow נמצא בנקודת קצה של יעד, הוא מופעל אחרי PostFlow של נקודת הקצה של ה-proxy.
2	תהליך מותנה	המקום שבו אפשר להשתמש בלוגיקה של משפט תנאי. ההרצה מתבצעת אחרי PreFlow ולפני PostFlow. רק תהליך מותנה אחד מופעל לכל פלח – התהליך הראשון שהתנאי שלו מחזיר את הערך true. כלומר, אפשר להפעיל זרימה מותנית אחת כחלק מכל אחת מהאפשרויות הבאות: פייפליין הבקשות של ProxyEndpoint פייפליין הבקשות של TargetEndpoint צינור עיבוד נתונים לתגובה של ProxyEndpoint צינור עיבוד התגובה של TargetEndpoint
3	PostFlow	זה מקום טוב לרישום נתונים ביומן, לשליחת התראה על כך שמשהו קרה במהלך עיבוד הבקשה וכו'. הפעולה מתבצעת אחרי רצפי פעולות מותנים ו-PreFlow. אם PostFlow נמצא בנקודת קצה של שרת proxy, ויש נקודת קצה של יעד, PostFlow של נקודת הקצה של שרת ה-proxy מופעל לפני PreFlow של נקודת הקצה של היעד.
4	PostClientFlow (proxy flow only)	רצף פעולות לרישום הודעות אחרי שהתשובה מוחזרת ללקוח.

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

הערה: בתהליך מותנה, התנאי מוערך גם בבקשה וגם בתגובה. אי אפשר להגדיר תנאים נפרדים לבקשה ולתשובה. רק זרימה מותנית אחת מופעלת – הזרימה הראשונה שהתנאי שלה מוערך כ-true.

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

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

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

ב-PostClientFlow אפשר לכלול רק את כללי המדיניות הבאים. אי אפשר להשתמש בכללי מדיניות אחרים ב-PostClientFlow:

• מדיניות FlowCallout^*
• המדיניות MessageLogging
• מדיניות ServiceCallout

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

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

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

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

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

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

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

כשמוסיפים לוגיקה לשרת ה-proxy, עושים זאת על ידי הוספת מדיניות לזרימות של שרת ה-proxy. בדיוק כמו שרצפי פעולות מופעלים ברצף (PreFlow,‏ Flow ואז PostFlow, כפי שמתואר בנושא הזה), התוכן של רצף פעולות מופעל ברצף.

הערה: מידע נוסף על מדיניות, כולל איך להוסיף אותה באמצעות המסוף ובקוד, זמין במאמר מהי מדיניות? לפרטים על צירוף מדיניות לתהליכים, אפשר לעיין במאמר בנושא תהליכים מותנים.

ההגדרה הבאה של זרימת העבודה מתייחסת לשלוש מדיניות (שהוגדרו במקומות אחרים בקובצי XML משלהן). המדיניות שאליה מתייחסת Verify-API-Key מופעלת לפני המדיניות שאליה מתייחסת Assign-Message. אחרי שתיהן מופעלת המדיניות שמיוצגת על ידי Quota.

<Flow name="Get Food Cart Menus">
  <Description>Get Food Cart Menus</Description>
  <Request>
    <Step>
      <Name>Verify-API-Key</Name>
    </Step>
    <Step>
      <Name>Assign-Message</Name>
    </Step>
    <Step>
      <Name>Quota</Name>
    </Step>
  </Request>
  <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

הערה: בקוד שלמעלה, תנאי הנתיב, (proxy.pathsuffix MatchesPath "/"), תמיד מתקיים כי תמיד יש התאמה ל-"/". לכן אפשר פשוט להסיר אותו מהרכיב Condition ולהשתמש רק בתנאי הפועל:

    <Condition>request.verb = "GET"</Condition>

ניפוי באגים בתהליכים

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

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

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

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

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

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

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