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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

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

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

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

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

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

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

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

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

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

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

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

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

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

PostClientFlow יכול לכלול את סעיפי המדיניות הבאים:

* במדיניות של הסבר על זרימה אפשר להפעיל רק תהליכים משותפים שעומדים בקריטריונים להיכלל ב-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 מוצג רצף כללי המדיניות הזה כשורה של סמלים, שכל סמל מייצג את המדיניות. הסמלים שמופיעים בנתיב הבקשה כוללים את: אימות מפתח API, הסרת מפתח API ומכסה

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

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

למידע נוסף על מעקב אחר שרתי proxy, עיינו בשימוש בכלי המעקב.

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

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

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

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

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