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

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

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

‫Flows הם אבני הבניין הבסיסיות של שרתי 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 או לנקודת קצה של יעד. קוד ה-proxy ל-API מחולק לקוד שמתקשר עם הלקוח של ה-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, יכולים להיות רצפים שמופעלים בתנאי. כך יש לכם אפשרות להגדיר כמה רצפים של לוגיקה, אבל רק אחד מהם יופעל בהתאם למצב של ה-proxy. רצף מותנה הוא אופציונלי אם אתם יכולים להפעיל את כל הלוגיקה ב-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 וב-ConditionalFlow.

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>

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