המסמך הזה עוסק ב-Apigee Edge.
למעבר אל
מסמכי התיעוד של Apigee X. info
הצהרות מותנות הן מבנה בקרה נפוץ בכל שפות התכנות. כמו שפת תכנות, הגדרת שרת ה-proxy ל-API תומכת בהצהרות מותנות ל-Flows, ל-Policies, ל-Steps ול-RouteRules. הגדרת הצהרות מותנות מאפשרת להגדיר התנהגות דינמית ל-API. ההתנהגות הדינמית הזו מאפשרת לכם לבצע פעולות כמו המרת XML ל-JSON רק למכשירים ניידים, או ניתוב לכתובת URL של קצה עורפי על סמך סוג התוכן או פועל ה-HTTP של הודעת הבקשה.
במאמר הזה נסביר איך להשתמש בתנאים כדי להחיל באופן דינמי תכונות של ניהול ממשקי API בזמן הריצה, בלי לכתוב קוד.
הגדרת הצהרות מותנות
התנהגות מותנית מיושמת בשרתי proxy ל-API באמצעות שילוב של תנאים ומשתנים. הצהרה מותנית נוצרת באמצעות רכיב Condition. התנאי הבא הוא תנאי ריק:
<Condition></Condition>
כדי ליצור הצהרה מותנית, מוסיפים אופרטור מותנה ומשתנה כדי ליצור את המבנה הבא:
<Condition>{variable.name}{operator}{"value"}</Condition>
אופרטורים מותנים נתמכים כוללים את = (שווה), != (לא שווה) ו-> (גדול מ-). כדי לשפר את הקריאוּת, אפשר גם לכתוב את התנאים כטקסט: equals, notequals, greaterthan.
כשעובדים עם נתיבי URI, אפשר להשתמש ב-~/ או ב-MatchesPath. אפשר גם להתאים ביטויים רגולריים של JavaRegex באמצעות האופרטור ~~.
תנאים משמשים להגדרת תהליכים מותנים של שרתי proxy ל-API למשאבי API לקצה העורפי, כפי שמתואר במאמר יצירת תהליכים מותנים למשאבי API לקצה העורפי. רשימה מלאה של תנאים מופיעה בחומרי העזר בנושא תנאים.
משתנים
התנאים פועלים על ידי הערכת הערכים של משתנים. משתנה הוא מאפיין של טרנזקציית HTTP שמבוצעת על ידי שרת proxy ל-API, או מאפיין של הגדרת שרת proxy ל-API עצמו. בכל פעם ש-proxy ל-API מקבל בקשה מאפליקציה, Apigee Edge מאכלס רשימה ארוכה של משתנים שמשויכים לדברים כמו זמן המערכת, פרטי הרשת של האפליקציה, כותרות HTTP בהודעות, הגדרת ה-proxy ל-API, הפעלות של מדיניות וכו'. כך נוצר הקשר עשיר שבו אפשר להשתמש כדי להגדיר הצהרות מותנות.
משתנים תמיד משתמשים בסימון עם נקודות. לדוגמה, כותרות HTTP בהודעת הבקשה זמינות כמשתנים שנקראים request.header.{header_name}. כדי להעריך את הכותרת Content-type, אפשר להשתמש במשתנה request.header.Content-type. לדוגמה, request.header.Content-type = "application/json" מציין שסוג התוכן של הבקשה צריך להיות JSON.
נניח שאתם צריכים ליצור הצהרה מותנית שתגרום לאכיפת מדיניות רק כשבקשת ההודעה היא GET. כדי ליצור תנאי שמעריך את פועל ה-HTTP של בקשה, יוצרים את ההצהרה המותנית הבאה. המשתנה בתנאי הזה הוא
request.verb. הערך של המשתנה הוא GET. האופרטור הוא =.
<Condition>request.verb = "GET"</Condition>
<Condition>request.verb equals "GET"</Condition>
Edge משתמש בהצהרה כזו כדי להעריך תנאים. הדוגמה שלמעלה תחזיר true אם הפועל של HTTP שמשויך לבקשה הוא GET. אם פועל ה-HTTP שמשויך לבקשה הוא POST, ההצהרה מקבלת את הערך false.
כדי להפעיל התנהגות דינמית, אפשר לצרף תנאים ל-Flows, ל-Steps ול-RouteRules.
כשמצרפים תנאי ל-Flow, יוצרים "Flow מותנה". תהליכים מותנים פועלים רק כשהתנאי מתקיים. אפשר לצרף כמה כללי מדיניות שרוצים לתהליך מותנה. Flow מותנה מאפשר ליצור כללי עיבוד מיוחדים מאוד להודעות בקשה או תגובה שעומדות בקריטריונים מסוימים.
לדוגמה, כדי ליצור Flow שמתבצע רק כשפועל הבקשה הוא GET:
<Flows> <Flow name="ExecuteForGETs"> <Condition>request.verb="GET"</Condition> </Flow> </Flows>
כדי ליצור Flow אחד לבקשות GET ו-Flow אחר לבקשות POST:
<Flows> <Flow name="ExecuteForGETs"> <Condition>request.verb="GET"</Condition> </Flow> <Flow name="ExecuteForPOSTs"> <Condition>request.verb="POST"</Condition> </Flow> </Flows>
כמו שמוצג בדוגמה הבאה, אפשר להחיל את התנאי על שלב המדיניות עצמו. התנאי הבא גורם לאכיפה של מדיניות VerifyApiKey רק אם הודעת הבקשה היא POST.
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>request.verb equals "POST"</Condition>
<Name>VerifyApiKey</Name>
</Step>
</Request>
</PreFlow>אחרי שמגדירים תהליכים מותנים כאלה, אפשר לצרף אליהם כללי מדיניות. כך proxy ל-API יכול לאכוף קבוצה אחת של כללי מדיניות על בקשות GET, וקבוצה אחרת של כללי מדיניות על בקשות POST.
למידע מקיף, אפשר לעיין במקורות המידע הבאים:
דוגמה 1
בדוגמה הבאה מוצג תהליך מותנה יחיד בשם Convert-for-devices, שמוגדר בתהליך התגובה של ProxyEndpoint. מוסיפים את התנאי כרכיב לישות שהתנאי חל עליה. בדוגמה הזו, התנאי הוא רכיב בתהליך.
לכן, התהליך יופעל בכל פעם שההצהרה תהיה נכונה.
<Flows>
<Flow name="Convert-for-devices">
<Condition>(request.header.User-Agent = "Mozilla")</Condition>
<Response>
<Step><Name>ConvertToJSON</Name></Step>
</Response>
</Flow>
</Flows>בכל בקשה שמתקבלת מאפליקציה, Edge מאחסן את הערכים של כל כותרות ה-HTTP שקיימות כמשתנים. אם הבקשה מכילה כותרת HTTP בשם User-Agent, הכותרת הזו והערך שלה נשמרים כמשתנה בשם request.header.User-Agent.
בהתאם להגדרת ProxyEndpoint שלמעלה, Edge בודק את הערך של המשתנה request.header.User-Agent כדי לראות אם התנאי מתקיים.
אם התנאי מתקיים, כלומר הערך של המשתנה request.header.User-Agent שווה ל-Mozilla, אז התהליך המותנה מופעל ומדיניות XMLtoJSON שנקראת ConvertToJSON נאכפת. אם לא, ה-Flow לא מופעל, והתגובה ב-XML מוחזרת ללא שינוי (בפורמט XML) לאפליקציה ששלחה את הבקשה.
דוגמה 2
נשתמש בדוגמה ספציפית שבה צריך להמיר הודעת תגובה מ-XML ל-JSON, אבל רק למכשירים ניידים. קודם יוצרים את המדיניות שתמיר את התגובה בפורמט XML מ-Weather API ל-JSON:
<XMLToJSON name="ConvertToJSON"> <Options> </Options> <OutputVariable>response</OutputVariable> <Source>response</Source> </XMLToJSON>
הגדרת המדיניות שלמעלה מורה ל-proxy ל-API לקחת את הודעת התגובה, לבצע המרה מ-XML ל-JSON עם הגדרות ברירת המחדל, ואז לכתוב את התוצאה בהודעת התגובה החדשה. (אם אתם ממירים הודעת בקשה מ-XML ל-JSON, פשוט מגדירים את שני הערכים האלה ל-request.)
כדי להמיר תשובות מ-XML ל-JSON, צריך להגדיר תהליך מותנה של תשובות שיבצע את ההמרה. לדוגמה, כדי להמיר את כל התגובות מ-XML ל-JSON לפני שהן מוחזרות לאפליקציית הלקוח, מגדירים את ה-Flow הבא של תגובת ProxyEndpoint.
<Flows>
<Flow name="Convert-for-devices">
<Response>
<Step><Name>ConvertToJSON</Name></Step>
</Response>
</Flow>
</Flows>כשמפעילים את ה-API באמצעות הבקשה הרגילה, התשובה מופיעה בפורמט JSON.
עם זאת, המטרה שלכם היא להמיר דוחות מזג אוויר ל-JSON רק כשהלקוח שמבקש הוא מכשיר נייד. כדי להפעיל התנהגות דינמית כזו, צריך להוסיף הצהרה מותנית לתהליך.
בדיקת התהליך המותנה
בבקשה לדוגמה, כותרת ה-HTTP User-Agent מוגדרת ל-Mozilla, וכתוצאה מכך ההצהרה המותנית מקבלת את הערך true והתהליך המותנה Convert-for-devices מופעל.
$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
או, כדי להדפיס בצורה יפה במקום שבו Python זמין:
$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282 | python -mjson.tool
תשובה לדוגמה:
. . .
"yweather_forecast": [
{
"code": "11",
"date": "12 Dec 2012",
"day": "Wed",
"high": "55",
"low": "36",
"text": "Showers"
},
{
"code": "32",
"date": "13 Dec 2012",
"day": "Thu",
"high": "56",
"low": "38",
"text": "Sunny"
}
]
}
. . .בקשה שנשלחת בלי הכותרת User-Agent, או עם ערך שונה מ-Mozilla, תגרום לתגובה בפורמט XML.
$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
תגובת ה-XML מוחזרת ללא שינוי.
תשובה לדוגמה:
<yweather:forecast day="Wed" date="12 Dec 2012" low="36" high="55" text="Showers" code="11" /> <yweather:forecast day="Thu" date="13 Dec 2012" low="38" high="56" text="Sunny" code="32" />
התאמת דפוסים
בקטע הזה מוסבר איך להשתמש בהתאמה לדפוסים עם תנאים בתהליך של Apigee.
אופרטורים
בקטע הזה מוסבר איך להשתמש באופרטורים הבאים להתאמת דפוסים בהצהרות מותנות:
- האופרטור "תואם": התאמה פשוטה של דפוסים
- אופרטור JavaRegex: שליטה מדויקת יותר בהתאמה
- האופרטור MatchesPath: התאמה של קטע נתיב
התאמות
קודם נסתכל על האופרטור המותנה "תואם" או "~". שני האופרטורים האלה זהים – הגרסה באנגלית, Matches, נחשבת לאפשרות קריאה יותר.
סיכום: האופרטור "תואם" נותן לכם שתי אפשרויות. אפשר להתאים את המחרוזת באופן מילולי, או לבצע התאמה לתווים כלליים לחיפוש באמצעות "*". כפי שניתן לצפות, התו הכללי לחיפוש תואם לאפס תווים או יותר. בואו נראה איך זה עובד.
ה-XML הבא מציג תנאי לביצוע השלב. היא מפעילה את המדיניות SomePolicy כשהתנאי
מוערך כ-true. בדוגמה הזו, אנחנו בודקים את המשתנה proxy.pathsuffix, משתנה מובנה ב-Edge שמאחסן את הסיומת של נתיב כתובת ה-URL של הבקשה. עם זאת, שימו לב שאפשר לבדוק את הערך של כל משתנה זרימה שמכיל מחרוזת. לכן, במקרה הזה, אם נתיב הבסיס של הבקשה הנכנסת הוא /animals והבקשה היא /animals/cat, הסיומת של נתיב כתובת ה-URL היא המחרוזת המילולית "/cat".
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>(proxy.pathsuffix Matches "/cat")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>שאלה: איזו סיומת של נתיב כתובת ה-URL של שרת ה-Proxy תגרום להפעלת SomePolicy? יש רק אפשרות אחת.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן, כי הסיומת של נתיב כתובת ה-URL של שרת ה-proxy תואמת בדיוק לערך "/cat". הוא לא יפעל אם הסיומת היא /bat או /dog או "/" או כל דבר אחר.
עכשיו, נבחן את ההצהרה המותנית הזו שבה אנחנו משתמשים בתו הכללי לחיפוש "*":
<Condition>(proxy.pathsuffix Matches "/*at")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן, כי התו הכללי לחיפוש תואם לכל תו, ו-""/cat" הוא התאמה.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/bat
האם המדיניות מופעלת? כן, כי התו הכללי לחיפוש תואם לכל תו, ולכן "/bat"
הוא התאמה.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/owl
האם המדיניות מופעלת? בהחלט לא – למרות שהתו הכללי לחיפוש תואם ל-"o",
האותיות "wl" לא תואמות.
עכשיו נעביר את התו הכללי לסוף הסיומת:
<Condition>(proxy.pathsuffix Matches "/cat*")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן, כי התו הכללי לחיפוש תואם לאפס תווים או יותר מכל סוג.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/bat
האם המדיניות מופעלת? לא, "/bat" לא מתאים.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat123
האם המדיניות מופעלת? כן, התו הכללי לחיפוש תואם לאפס תווים או יותר, ולכן
"123" מייצר התאמה.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat/bird/mouse
האם המדיניות מופעלת? כן, כי התו הכללי לחיפוש תואם לאפס תווים או יותר, ולכן "/bird/mouse" מייצר התאמה. שימו לב שביטוי כזה יכול לגרום לבעיות כי הוא תואם לכל מה שמופיע אחרי התווים המילוליים.
שאלה: האם האופרטור "תואם" תלוי אותיות רישיות?
כן. נניח שיש לכם תנאי כזה:
<Condition>(proxy.pathsuffix Matches "/*At")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? לא, התו הכללי לחיפוש תואם לכל אות (ללא קשר לאותיות רישיות), אבל האות הקטנה "a" לא תואמת לאות הרישית "A".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/bAt
האם המדיניות מופעלת? כן, יש התאמה.
שאלה: איך מוסיפים תווי בריחה (escape) לאופרטור Matches?
כדי להחליף תווים שמורים, משתמשים בתו האחוז "%". לדוגמה:
<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? לא, האופרטור Matches מחפש את המחרוזת המילולית "c*at".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/c*at
שאלה:האם המדיניות מופעלת?
כן, הנתיב הזה מתאים, למרות שהוא קצת חריג.
JavaRegex
כמו שאפשר לראות, האופרטור "תואם" מתאים למצבים פשוטים. אבל אתם יכולים להשתמש באופרטור אחר, "JavaRegex" או "~~". שני האופרטורים האלה זהים, אבל JavaRegex נחשב לקריא יותר. היא נקראת JavaRegex כי היא מאפשרת התאמה של דפוסי ביטויים רגולריים, ו-Edge פועלת לפי אותם כללים כמו המחלקות בחבילת java.util.regex בשפת Java. האופן שבו האופרטור JavaRegex פועל שונה מאוד מהאופן שבו האופרטור Matches פועל, ולכן חשוב לא להתבלבל ביניהם.
סיכום: האופרטור JavaRegex מאפשר להשתמש בתחביר של ביטויים רגולריים בהצהרות מותנות.
הקוד הבא מציג תנאי לביצוע השלב. היא מפעילה את המדיניות SomePolicy אם התנאי מתקיים. בדוגמה הזו, אנחנו בודקים את המשתנה proxy.pathsuffix, משתנה מובנה ב-Edge שמאחסן את הסיומת של נתיב כתובת ה-URL של הבקשה. אם נתיב הבסיס של הבקשה הנכנסת הוא /animals והבקשה היא /animals/cat, הסיומת של נתיב כתובת ה-URL היא המחרוזת המילולית "/cat".
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>שאלה: איזו סיומת של נתיב כתובת ה-URL של שרת ה-Proxy תגרום להפעלת SomePolicy? כמו במקרה של האופרטור Matches, גם במקרה הזה יש רק אפשרות אחת.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן, כי הסיומת של נתיב כתובת ה-URL של שרת ה-proxy תואמת בדיוק לערך "/cat". הוא לא יופעל אם הסיומת היא /bat או /dog או כל דבר אחר.
עכשיו ניצור ביטוי רגולרי באמצעות הכַּמָּת "*". הכַּמָּת הזה תואם לאפס או יותר מהתו הקודם.
<Condition>(proxy.pathsuffix JavaRegex "/c*t")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? לא! הכמת "*" תואם לאפס או יותר תווים שלפניו, שהם "c".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/ccccct
האם המדיניות מופעלת? כן, כי התו הכללי לחיפוש תואם לאפס או יותר מהתו הקודם.
בשלב הבא, אנחנו משתמשים בכַמָּת "?", שתואם לתו הקודם פעם אחת או בכלל לא.
<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן. הכַּמָּת "?" תואם לאפס מופעים או למופע אחד של התו הקודם, שהוא "a".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/ct
האם המדיניות מופעלת? כן. הכַּמָּת "?" תואם לתו הקודם פעם אחת או לא תואם לו בכלל. במקרה הזה, אין את התו "a", ולכן התנאי מחזיר True.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/caat
האם המדיניות מופעלת? לא. הכמת "?" תואם לאחד מהתווים הקודמים, שהוא "a".
בשלב הבא, אנחנו משתמשים בסגנון "[abc]" או "קיבוץ" של ביטוי רגולרי. הוא תואם לתווים "a" או "b" או "c".
<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן. אנחנו משתמשים כאן בביטויים רגולריים, והביטוי "[cbr]" תואם ל-"c", "b" או "r". גם השיחות האלה הן התאמות:
GET http://artomatic-test.apigee.net/matchtest/bat
GET http://artomatic-test.apigee.net/matchtest/rat
אבל זה לא נחשב התאמה:
GET http://artomatic-test.apigee.net/matchtest/mat
שאלה: האם האופרטור JavaRegex תלוי אותיות רישיות?
כן. נניח שיש לכם תנאי כזה:
<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
האם המדיניות מופעלת? כן, הביטוי הרגולרי תואם לאפס או לאחד מהתווים הקודמים, שהם "a".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cAt
שאלה: האם המדיניות מופעלת?
לא, כי האות הגדולה "A" לא תואמת לאות הקטנה "a".
MatchesPath
אפשר לציין את האופרטור MatchesPath גם כך: "~/". הוא דומה קצת לאופרטורים Matches (~) ו-JavaRegex (~~). אבל MatchesPath שונה לגמרי.
חשוב לזכור שהאופרטור הזה מתייחס לנתיב כסדרה של חלקים. לכן, אם הנתיב הוא /animals/cats/wild, אפשר לחשוב על הנתיב כמורכב מהחלקים "/animals", "/cats" ו-"/wild".
האופרטור MatchesPath מאפשר להשתמש בשני סימונים של תווים כלליים לחיפוש: כוכבית אחת (*) וכוכבית כפולה (**). הכוכבית האחת תואמת לרכיב נתיב אחד. שתי כוכביות תואמות לרכיב אחד או יותר בנתיב.
נתבונן בדוגמה. בדוגמה הזו, אנחנו בודקים את המשתנה proxy.pathsuffix, משתנה מובנה ב-Edge שמאחסן את הסיומת של נתיב כתובת ה-URL של הבקשה. עם זאת, שימו לב שאפשר לבדוק את הערך של כל משתנה זרימה שמכיל מחרוזת.
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>שאלה: איזו סיומת של נתיב כתובת ה-URL של שרת ה-Proxy תגרום להפעלת SomePolicy?
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals
שאלה: האם המדיניות מופעלת?
לא, כי התנאי דורש רכיב נתיב נוסף אחרי "/animals", כפי שצוין על ידי "/*".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/
האם המדיניות מופעלת? כן, לנתיב יש רכיב נתיב נוסף (החלק שאחרי "/animals/"), אבל הוא פשוט ריק.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/cats
האם המדיניות מופעלת? כן, כי בנתיב יש בבירור רכיב ("/cats")
שמופיע אחרי "/animals"
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild
שאלה: האם המדיניות מופעלת?
לא, כי הכוכבית הבודדת תואמת רק לרכיב נתיב אחד, ול-API הזה יש יותר מרכיב אחד אחרי "/animals".
עכשיו נשתמש בכוכבית כפולה:
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>שאלה: איזו סיומת של נתיב כתובת ה-URL של שרת ה-Proxy תגרום להפעלת SomePolicy?
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals
האם המדיניות מופעלת? לא, כי התנאי דורש לפחות רכיב נתיב אחד אחריו, שצוין על ידי "/**".
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/
האם המדיניות מופעלת?
כן, לנתיב יש רכיב נתיב נוסף (החלק שאחרי "/animals/"), אבל הוא פשוט ריק.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/cats
האם המדיניות מופעלת?
כן, כי הנתיב כולל לפחות רכיב אחד שמופיע אחרי "/animals"
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild
האם המדיניות מופעלת?
כן, כי בנתיב יש יותר מרכיב אחד שמופיע אחרי "/animals"
ערבוב של כוכביות
אפשר להשתמש בשילובים של כוכבית אחת (*) ושתי כוכביות (**) כדי לחדד עוד יותר את ההתאמה לנתיב.
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>קריאה ל-API:
כל הקריאות האלה ל-API יניבו התאמה:
GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild/
וגם
GET http://artomatic-test.apigee.net/matchtest/animals/dogs/wild/austrailian
וגם
GET
http://artomatic-test.apigee.net/matchtest/animals/birds/wild/american/finches
משאבי API
שירותי RESTful הם אוספים של משאבי API. משאב API הוא קטע של נתיב URI שמזהה ישות כלשהי שמפתחים יכולים לגשת אליה על ידי קריאה ל-API. לדוגמה, אם השירות שלכם מספק דוחות ותחזיות של מזג האוויר, השירות לקצה העורפי יכול להגדיר שני משאבי API:
- http://mygreatweatherforecast.com/reports
- http://mygreatweatherforecast.com/forecasts
כשיוצרים proxy ל-API (כפי שמוצג במאמר יצירת ה-proxy הראשון ל-API), יוצרים לפחות כתובת URL בסיסית של כינוי שממפה לשירות לקצה העורפי. לדוגמה:
| כתובת ה-URL הבסיסית של הקצה העורפי | כתובת URL חדשה או מקבילה של שרת proxy ל-API |
|---|---|
| http://mygreatweatherforecast.com | http://{your_org}-{environment}.apigee.net/mygreatweatherforecast |
בשלב הזה, אתם יכולים לבצע קריאות ל-API לקצה העורפי באמצעות כל אחת מכתובות ה-URL הבסיסיות. אבל כשמשתמשים בכתובת ה-URL של שרת ה-proxy ל-API, הדברים מתחילים להיות מעניינים.
בנוסף לניתוח הנתונים של ה-API ש-Edge מתחיל לאסוף כשמשתמשים בשרת proxy ל-API, שרתי proxy גם מאפשרים להגדיר תהליכים מותנים שממופים למשאבים בקצה העורפי. במילים אחרות, "אם מתקבלת קריאת GET למשאב /reports, Edge צריך לעשות משהו".
התמונה הבאה מציגה את ההבדל בהתנהגות בין שתי כתובות URL שבסופו של דבר ניגשות לאותו קצה עורפי. אחד הוא כתובת ה-URL של המשאב ללא שרת proxy, והשני הוא שרת proxy של Edge API עם תהליך מותנה לאותו משאב בקצה העורפי. בהמשך נתאר את התהליכים המותנים בפירוט רב יותר.

איך שרתי proxy ל-API ממפים למשאבים ספציפיים בקצה העורפי
כשיוצרים את ה-proxy, ממפים את כתובת ה-URL של ה-proxy ל-API לכתובת ה-URL הבסיסית של שירות הקצה העורפי. אחרי שעושים את זה, אפשר להוסיף תהליכים מותנים למשאבים ספציפיים, כמו המשאבים /reports ו-/forecasts שהוזכרו קודם.
נניח שאתם רוצים ש-Edge "יעשה משהו" כשמגיעות שיחות למשאבים /reports או /forecasts. בשלב הזה אתם לא אומרים ל-Edge מה לעשות, אלא רק שהוא צריך להאזין לקריאות למשאבים האלה. כדי לעשות את זה, משתמשים בתנאים. ב-proxy ל-Edge API, אתם יכולים ליצור תהליכים מותנים ל-/reports ול-/forecasts. למטרות המחשה, קוד ה-XML הבא של proxy ל-API מראה איך התנאים האלה עשויים להיראות.
<Flows>
<Flow name="reports">
<Description/>
<Request/>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>
<Flow name="forecasts">
<Description/>
<Request/>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
</Flow>
</Flows>התנאים האלה אומרים: "כשמגיעה בקשת GET עם /reports ו-/forecasts בכתובת ה-URL, Edge יעשה כל מה שאתם (מפתחי ה-API) תגידו לו, באמצעות כללי המדיניות שאתם מצרפים לתהליכים האלה.
עכשיו נראה דוגמה שבה אומרים ל-Edge מה לעשות כשמתקיים תנאי מסוים. ב-XML הבא של שרת proxy ל-API, כשבקשת GET נשלחת אל https://yourorg-test.apigee.net/mygreatweatherforecast/reports, Edge מפעיל את המדיניות XML-to-JSON-1 בתגובה.
<Flows>
<Flow name="reports">
<Description/>
<Request/>
<Response>
<Step>
<Name>XML-to-JSON-1</Name>
</Step>
</Response>
<Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>בנוסף לתהליכים המותנים האופציונליים האלה, כל שרת proxy ל-API כולל גם שני תהליכי ברירת מחדל: <PreFlow> שמתבצע לפני התהליכים המותנים, ו-<PostFlow> שמתבצע אחרי התהליכים המותנים. הם שימושיים להפעלת כללי מדיניות כשמתבצעת קריאה כלשהי ל-proxy ל-API. לדוגמה, אם רוצים לאמת את מפתח ה-API של אפליקציה בכל קריאה, בלי קשר למשאב בקצה העורפי שאליו ניגשים, אפשר להוסיף מדיניות Verify API Key ל-<PreFlow>. מידע נוסף על תהליכים מופיע במאמר הגדרת תהליכים.
יצירת תהליכים מותנים למשאבי קצה עורפי
הגדרת תהליכים מותנים למשאבי קצה עורפי בשרת proxy ל-API היא אופציונלית לחלוטין. עם זאת, התהליכים המותנים האלה מאפשרים לכם להחיל ניהול ומעקב מפורטים.
תוכלו:
- להחיל ניהול באופן שמשקף את הסמנטיקה של מודל ה-API
- החלת כללי מדיניות והתנהגות מבוססת-סקריפט על נתיבי משאבים (URI) ספציפיים
- איסוף מדדים מפורטים לשירותי Analytics
לדוגמה, נניח שאתם צריכים להחיל סוגים שונים של לוגיקה על המשאבים שלכם ב-backend, מ-/developers עד /apps.
כדי לעשות את זה, מוסיפים שני תהליכים מותנים ב-proxy ל-API: /developers ו-/apps.
בתצוגה Develop בחלונית הניווט של עורך ה-proxy ל-API, לוחצים על הסמל + ליד ברירת המחדל ב-Proxy Endpoints.
![]()
בחלון New Conditional Flow (תהליך מותנה חדש), מזינים את הגדרות המפתח הבאות:
- שם התהליך: מפתחים
- סוג התנאי: נתיב
- נתיב: /developers

התנאי יופעל (והמדיניות תבוצע) אם תישלח קריאה לשרת ה-proxy עם /developers בסוף ה-URI.
עכשיו נוסיף תהליך מותנה ל-/apps, ונניח שאתם רוצים שהתנאי יופעל גם ב-URI וגם בפועל POST בבקשה. ההגדרה כוללת את השלבים הבאים:
- שם התהליך: אפליקציות
- סוג התנאי: נתיב ופועל
- נתיב: /apps
- פועל: POST

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

בוחרים אחד מהתהליכים כדי להציג את ההגדרה של התהליך המותנה בתצוגת הקוד של עורך ה-proxy ל-API:
<Flow name="Apps"> <Description>Developer apps registered in Developer Services</Description> <Request/> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition> </Flow>
כמו שאפשר לראות, משאבי API הם פשוט תהליכים מותנים שמעריכים את נתיב ה-URI של הבקשה הנכנסת. (המשתנה proxy.pathsuffix מזהה את ה-URI של הבקשה שמופיע אחרי BasePath שהוגדר ב-ProxyEndpoint).
כל משאב API שאתם מגדירים מוטמע על ידי תהליך מותנה ב-proxy ל-API. (ראו הגדרת תהליכים).
אחרי שפורסים את ה-proxy ל-API בסביבת הבדיקה, הבקשה הבאה:
http://{org_name}-test.apigee.net/{proxy_path}/appsתגרום לכך שהתנאי יקבל את הערך true, והתהליך הזה, יחד עם כל כללי המדיניות שמשויכים אליו, יופעל.
בתנאי לדוגמה הבא נעשה שימוש בביטוי רגולרי של Java כדי לזהות קריאות שבוצעו למשאב /apps עם או בלי קו נטוי בסוף (/apps או /apps/**):
<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>
למידע נוסף על סוג התנאי הזה, ראו How to match regardless ... בקהילת Apigee.
בניית מודלים של מזהי URI היררכיים
במקרים מסוימים, יהיו לכם משאבי API היררכיים. לדוגמה, ב-Developer Services API יש שיטה להצגת רשימה של כל האפליקציות ששייכות למפתח. נתיב ה-URI הוא:
/developers/{developer_email}/appsיכול להיות שיש לכם משאבים שבהם נוצר מזהה ייחודי לכל ישות באוסף, שלפעמים מסומן כך:
/genus/:id/species
הנתיב הזה חל באופן שווה על שני ה-URI הבאים:
/genus/18904/species /genus/17908/species
כדי לייצג את המבנה הזה במשאב API, אפשר להשתמש בתווים כלליים לחיפוש. לדוגמה:
/developers/*/apps
/developers/*example.com/apps
/genus/*/species
יפתור את מזהי ה-URI ההיררכיים האלה כמשאבי API בהתאם.
במקרים מסוימים, במיוחד בממשקי API עם היררכיה עמוקה, יכול להיות שתרצו לפתור את כל מה שמתחת לקטע URI מסוים. כדי לעשות את זה, משתמשים בתו כללי של כוכבית כפולה בהגדרת המשאב. לדוגמה, אם מגדירים את משאב ה-API הבא:/developers/**
משאב ה-API הזה יפתור את נתיבי ה-URI הבאים:
/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keysכך ייראה התנאי של התהליך המותנה בהגדרה של ה-proxy ל-API:
<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>
דוגמאות נוספות
תנאי שמצורף ל-RouteRule
<RouteRule name="default"> <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint--> <Condition>request.header.content-type = "text/xml"</Condition> <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint> </RouteRule>
תנאי שמצורף למדיניות
<Step> <!--the policy MaintenancePolicy only executes if the response status code is exactly 503--> <Condition>response.status.code = 503</Condition> <Name>MaintenancePolicy</Name> </Step>
תהליך מותנה
<!-- this entire flow is executed only if the request verb is a GET--> <Flow name="GetRequests"> <Condition>request.verb="GET"</Condition> <Request> <Step> <!-- this policy only executes if request path includes a term like statues--> <Condition>request.path ~ "/statuses/**"</Condition> <Name>StatusesRequestPolicy</Name> </Step> </Request> <Response> <Step> <!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400--> <Condition>(response.status.code = 503) or (response.status.code = 400)</Condition> <Name>MaintenancePolicy</Name> </Step> </Response> </Flow>
אופרטורים לדוגמה בתנאים
הנה כמה דוגמאות לאופרטורים שמשמשים ליצירת תנאים:
request.header.content-type = "text/xml"request.header.content-length < 4096 && request.verb = "PUT"response.status.code = 404 || response.status.code = 500request.uri MatchesPath "/*/statuses/**"request.queryparam.q0 NotEquals 10
דוגמה מעשית: התעלמות מ-"/" בסוף נתיב
מפתחי Edge בדרך כלל רוצים לטפל בשתי הסיומות האלה של נתיב כתובת ה-URL: "/cat" ו-"/cat/". הסיבה לכך היא שחלק מהמשתמשים או הלקוחות עשויים לקרוא ל-API עם לוכסן נוסף בסוף הנתיב, ואתם צריכים להיות מסוגלים לטפל בכך בהצהרות המותנות שלכם. תרחיש השימוש הספציפי הזה נדון בקהילת Apigee.
אם אתם מעדיפים, אתם יכולים לעשות את זה בלי להשתמש בביטויים רגולריים, באופן הבא:
<PreFlow name="PreFlow">
<Request>
<Step>
<Condition>((proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
<Name>SomePolicy</Name>
</Step>
</Request>
<Response/>
</PreFlow>זו אפשרות טובה. התמונה ברורה וקריאה.
אבל אפשר לעשות את אותו הדבר גם באמצעות ביטויים רגולריים, למשל: הסוגריים משמשים לקיבוץ החלק של הביטוי הרגולרי בהצהרה, אבל הם לא חובה.
<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>
קריאות ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat
or
GET http://artomatic-test.apigee.net/matchtest/cat/
האם המדיניות מופעלת? כן. שימו לב שבביטוי רגולרי, התו "?" פירושו: התאמה לאפס תווים או לתו אחד מהתו הקודם. לכן, גם "/cat" וגם "/cat/" הן התאמות.
קריאה ל-API:
GET http://artomatic-test.apigee.net/matchtest/cat/spotted
האם המדיניות מופעלת? לא. הביטוי הרגולרי תואם לאפס מופעים או למופע אחד בלבד של התו הקודם, ואסור להשתמש בשום דבר אחר.
התאמת מחרוזות שרירותיות באמצעות JavaRegex
בכל הדוגמאות בנושא הזה, אנחנו מראים איך להתאים לאחד ממשתני הזרימה המובנים: proxy.pathsuffix. חשוב לדעת שאפשר לבצע התאמה לתבנית בכל מחרוזת או משתנה זרימה שרירותיים, בין אם מדובר במשתנה זרימה מובנה כמו proxy.pathsuffix ובין אם לא.
לדוגמה, אם יש לכם תנאי שבודק מחרוזת שרירותית, אולי מחרוזת שמוחזרת במטען ייעודי (payload) לקצה העורפי, או מחרוזת שמוחזרת מחיפוש בשרת אימות, אתם יכולים להשתמש באופרטורים של התאמה כדי לבדוק אותה. אם משתמשים ב-JavaRegex, הביטוי הרגולרי יושווה לכל מחרוזת הנושא. אם הנושא הוא "abc" והביטוי הרגולרי הוא "[a-z]", אין התאמה, כי "[a-z]" תואם בדיוק לתו אלפביתי אחד. הביטוי "[a-z]+" פועל, כמו גם "[a-z]*" ו-"[a-z]{3}.
נבחן דוגמה קונקרטית. נניח ששרת האימות מחזיר רשימה של תפקידים כמחרוזת שמופרדת בפסיקים: "editor, author, guest".
כדי לבדוק אם קיימת הרשאת עריכה, המבנה הזה לא יעבוד, כי "עריכה" היא רק חלק מהמחרוזת כולה.
<Condition>returned_roles ~~ "editor"</Condition>
אבל המבנה הזה כן יעבוד:
<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>
הוא פועל כי הוא מביא בחשבון מעברי מילים וכל חלק אחר במחרוזת עם התחילית והסיומת .* .
בדוגמה הזו, אפשר גם לבדוק את הערך "editor" באמצעות האופרטור "תואם":
<Condition>returned_roles ~~ "*editor*")</Condition>
עם זאת, במקרים שבהם נדרש דיוק רב יותר, JavaRegex היא בדרך כלל בחירה טובה יותר.
תווי בריחה (escape) למירכאות כפולות בביטויי JavaRegex
התחביר של Condition דורש שביטוי JavaRegex יהיה מוקף במירכאות כפולות. לכן, אם יש לכם ביטוי Regex שכולל מירכאות כפולות, אתם צריכים דרך חלופית להתאים אותן. התשובה היא Unicode. לדוגמה, נניח שאתם מעבירים כותרת שכוללת מירכאות כפולות, כמו בדוגמה הבאה:-H 'content-type:multipart/related; type="application/xop+xml"'
request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"
\u0022. לדוגמה, הביטוי הבא תקין ומפיק את התוצאה הצפויה:
request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"