דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

גם נקודת הקצה (endpoint) של שרת ה-Proxy ונקודת הקצה (endpoint) של היעד מכילים תהליכים שאפשר לארגן לפי הרצף הבא:

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

הפעלת הקוד קודם באמצעות PreFlow

כדאי להשתמש ב-PreFlow כשצריך לוודא שקוד מסוים פועל לפני משהו אחר.

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

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

בדוגמה הבאה, המדיניות של SpikeArrest ומדיניות המכסות פועלות לפני שהעיבוד עובר לתהליכים מותנים.

<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 יכול לכלול את כללי המדיניות הבאים:

^* ניתן להפעיל את המדיניות FlowCallout בהן רק על תהליכי עבודה משותפים שעומדים בקריטריונים להשתתפות ב-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 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>

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