תנאים עם משתני זרימה

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

הצהרות מותנות הן מבנה בקרה נפוץ בכל שפות התכנות. לסמן לייק על שפת התכנות, ההגדרות של שרת ה-proxy ל-API תומכות בהצהרות מותנות ל-Fflows, מדיניות, שלבים וכללי נתיב. הגדרת הצהרות מותנות מאפשרת להגדיר התנהגות דינמית ל-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}. אז כדי להעריך את המודל כותרת של סוג תוכן, אפשר להשתמש במשתנה 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, לשלבים ול-RouteRules.

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

לדוגמה, כדי ליצור תהליך שפועל רק כאשר פועל הבקשה הוא GET:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
</Flows>

כדי ליצור תהליך אחד לבקשות GET ותהליך נוסף ל-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>

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

תוכלו להיעזר במקורות המידע הבאים כדי לקבל מידע מקיף:

דוגמה 1

הדוגמה הבאה מציגה זרימה מותנה אחת בשם Convert-for-devices, שהוגדר בתהליך התגובה של ProxyEndpoint. צריך להוסיף את התנאי כרכיב לישות כדי שהתנאי חל עליו. בדוגמה הזו, התנאי הוא רכיב של התהליך. לכן, התהליך יתבצע בכל פעם שההצהרה מוערכת כ-True.

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

אם התנאי מקבל את הערך True, הערך של המשתנה request.header.User-Agent שווה ל-Mozilla, ואז הזרימה המותנית מופעל, ומדיניות XMLtoJSON בשם ConvertToJSON נאכפת. אם לא, לא מבוצעת, ותגובת ה-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 לפני שהם מוחזרים לאפליקציית הלקוח, צריך להגדיר את התגובה הבאה של ProxyEndpoint זרימה.

<Flows>
  <Flow name="Convert-for-devices">
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

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

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

בדיקת התנאי זרימה

בבקשה לדוגמה הזו, הכותרת User-Agent של HTTP מוגדרת בתור 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.

אופרטורים

בקטע הזה מוסבר איך להשתמש באופרטורים הבאים להתאמת תבניות באופן מותנה הצהרות

משחקים

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

סיכום: ה"התאמות" נותן לך שתי אפשרויות. אחת מהאפשרויות מחרוזת מילולית, או התאמה של תו כללי לחיפוש עם "*". כפי שאפשר לצפות, התו הכללי לחיפוש תואם לאפס או יותר תווים. עכשיו נראה איך זה עובד.

.

ב-XML הבא מוצג תנאי של שלב. היא מפעילה את מדיניות somePolicy כשהתנאי הפונקציה מחזירה את הערך True. בדוגמה הזאת אנחנו בודקים את המשתנה proxy.pathsuffix, משתנה מובנה ב-Edge שמאחסן את סיומת הנתיב של הבקשה. עם זאת, שימו לב שאפשר לבדוק הערך של כל משתנה זרימה שמכיל מחרוזת. אז במקרה הזה, אם הנתיב הבסיסי של הבקשה הנכנסת היא /animals, והבקשה היא /animals/cat, ואז הערך של הפרמטר סיומת הנתיב היא המחרוזת המילולית "/cat".

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix Matches "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

שאלה: איזו סיומת של נתיב של שרת proxy תגרום להפעלה של somePolicy? יש רק אפשרות אחת.

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/cat

האם המדיניות מופעלת? כן, כי הסיומת של נתיב שרת ה-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".

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/bAt

האם המדיניות מופעלת? כן, הפנייה תואמת.

שאלה: איך מוסיפים בתו בריחה (escape) תווים באמצעות האופרטור Matches?

שימוש באחוז '%' כדי לסמן בתו בריחה (escape) תווים שמורים. לדוגמה:

<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/cat

האם המדיניות מופעלת? לא, האופרטור 'התאמות' מחפש את המילה "c*at".

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/c*at

שאלה:האם המדיניות מופעלת?

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

JavaRegex

כמו שאפשר לראות, הקטע 'התאמות' הוא מעולה במצבים פשוטים. אבל אפשר להשתמש במודל אחר באופרטור JavaRegex או '~~' . שני האופרטורים האלה זהים, אבל JavaRegex נחשבים לקריאים יותר. היא נקראת JavaRegex כי היא מאפשרת ביטוי רגולרי התאמת דפוסים, ו-Edge פועל לפי אותם כללים כמו המחלקות ב-java.util.regex. חבילה בשפת Java. אופן הפעולה של האופרטור JavaRegex שונה מאוד מתאים לאופרטור, לכן חשוב לא להתבלבל בין השניים!

סיכום: ה-"JavaRegex" מאפשר להשתמש בתחביר של ביטויים רגולריים הצהרות מותנות.

הקוד הבא מציג תנאי של שלב. היא מפעילה את מדיניות somePolicy אם התנאי הפונקציה מחזירה את הערך True. בדוגמה הזאת אנחנו בודקים את המשתנה proxy.pathsuffix, ב-Edge שמאחסן את סיומת הנתיב של הבקשה. אם הנתיב הבסיסי של הבקשה הנכנסת היא /animals, והבקשה היא /animals/cat, ואז הערך של הפרמטר סיומת הנתיב היא המחרוזת המילולית "/cat".

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

שאלה: איזו סיומת של נתיב של שרת proxy תגרום להפעלה של somePolicy? בדיוק כמו בעזרת האופרטור Matches, יש רק אפשרות אחת במקרה הזה.

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/cat

האם המדיניות מופעלת? כן, כי הסיומת של נתיב שרת ה-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

האם המדיניות מופעלת? כן. ה'?' המכמת מתאים ל-0 או למופע אחד של התו הקודם, שהוא 'a'.

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/ct

האם המדיניות מופעלת? כן. ה'?' כמת מתאים לאחד או ללא מהתו הקודם. במקרה הזה, אין , כך התנאי מקבל את הערך True.

קריאה ל-API:

GET http://artomatic-test.apigee.net/matchtest/caat

האם המדיניות מופעלת? לא. סימן ה-"?" המכמת מתאים לאחד מהמאפיינים הקודמים שהוא "a".

בשלב הבא, אנחנו משתמשים ב-"[abc]" או 'קיבוץ' של ביטוי רגולרי (regex). הוא תואם ל- תווים "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 שמאחסן את סיומת הנתיב של הבקשה. אבל כדאי לשים לב: לבדוק את הערך של כל משתנה זרימה שמכיל מחרוזת.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

שאלה: איזו סיומת של נתיב של שרת 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>

שאלה: איזו סיומת של נתיב של שרת 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 הבסיסיות. אבל כשמשתמשים את כתובת האתר של ה-Proxy ל-API, דברים מתחילים להיות מעניינים.

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

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

איך שרתי proxy ל-API ממופים למשאבים ספציפיים בקצה העורפי

באמצעות כתובת URL של שרת proxy ל-API שממופה לכתובת ה-URL הבסיסית של שירות הקצה העורפי (כשיוצרים את שרת proxy), אפשר להוסיף תהליכים מותנים למשאבים ספציפיים, כמו /reports וגם /forecasts מקורות מידע שהוזכרו קודם לכן.

נניח שרציתם לבקש מ-Edge " לעשות משהו" כששיחות מגיעות /reports או /forecasts משאבים. בשלב הזה לא אומרים ל-Edge מה לעשות, רק שהוא צריך להקשיב לשיחות למשאבים האלה. עושים את זה עם תנאים. בשרת ה-proxy של Edge API אפשר ליצור תהליכים מותנים עבור /reports וגם /forecasts למטרות רעיוניות, ה-API הבא ה-XML של שרת ה-proxy מראה איך התנאים האלה עשויים להיראות.

<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 מה לעשות כשתנאי מסוים מתקיים. ב-API הבא XML של שרת proxy, כשבקשת GET נשלחת אל https://yourorg-test.apigee.net/mygreatweatherforecast/reports, דפדפן Edge פועל הקובץ "XML ל-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 של אפליקציה בכל קריאה, ללא קשר למשאב העורפי שמתבצעת אליו גישה, ניתן להוסיף מדיניות אימות מפתח API ב-<PreFlow>. למידע נוסף על תהליכים, אפשר לעיין במאמר הגדרת תהליכי עבודה.

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

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

בפורטל תוכלו:

  • להחיל את הניהול באופן שמשקף את הסמנטיקה של מודל ה-API
  • החלת כללי מדיניות והתנהגות באמצעות סקריפטים על נתיבי משאבים בודדים (URI)
  • איסוף מדדים פרטניים לשירותי Analytics

לדוגמה, נניח שצריך להחיל סוגים שונים של לוגיקה על הקצה העורפי. //developers למשאבים /apps.

כדי לעשות זאת, צריך להוסיף שני תהליכי עבודה מותנים בשרת ה-proxy ל-API: /developers ו /apps.

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

ב'תהליך מותנה חדש' צריך להזין את הגדרות המפתח הבאות:

  • Flow name: מפתחים
  • Condition Type: נתיב
  • נתיב: /developers

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

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

  • Flow Name: אפליקציות
  • Condition Type: נתיב ופועל
  • Path: /apps
  • Verb: POST

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

בחלונית Navigator יופיעו תהליכים חדשים לאפליקציות מפתחים.

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

למידע נוסף על סוג התנאי הזה, ראו איך להתאים ללא קשר ... בקהילת Apigee.

בניית מודלים של מזהי URI היררכיים

בחלק מהמקרים יהיו לכם משאבי API היררכיים. לדוגמה, השירותים למפתחים ב-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 = 500
  • request.uri MatchesPath "/*/statuses/**"
  • request.queryparam.q0 NotEquals 10

דוגמה מעשית: התעלמות מ-"/" ב סוף דרך

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

אם אתם מעדיפים, תוכלו לעשות זאת בלי להשתמש בביטוי רגולרי (regex): באופן הבא:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>((proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

זאת אפשרות טובה. היא ברורה וקריאה.

אבל אפשר לעשות את אותו הדבר עם Regex. הסוגריים משמשים לקיבוץ את החלק הרגולרי בהצהרה, אך הם לא נדרשים.

<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}.

נבחן דוגמה קונקרטית. נניח ששרת האימות מחזיר רשימת תפקידים מחרוזת עם הפחתה בפסיקים: "עורך, מחבר, אורח".

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

<Condition>returned_roles ~~ "editor"</Condition>

עם זאת, המבנה הזה יפעל:

<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>

התכונה פועלת כי היא מביאה בחשבון מעברי מילים וכל חלק אחר של המחרוזת עם תחילית וסיומת .*

בדוגמה הזו אפשר גם לבדוק את הערך 'Editor'. באמצעות האופרטור Matches:

<Condition>returned_roles ~~ "*editor*")</Condition>

עם זאת, במקרים שבהם נדרש דיוק רב יותר, מומלץ בדרך כלל להשתמש ב-JavaRegex.

סימון מירכאות כפולות בתו בריחה (escape) בביטויי JavaRegex

התחביר של התנאי דורש שביטוי JavaRegex יהיה מוקף במירכאות כפולות; ולכן אם יש לך ביטוי רגולרי שכולל מירכאות כפולות, צריך דרך חלופית להתאים להם. התשובה היא Unicode. לדוגמה, נניח שאתם מעבירים בכותרת שיש בה מירכאות כפולות, למשל: 
 -H 'content-type:multipart/related; type="application/xop+xml"'
 אם תנסו להתאים את הכותרת בתנאי של Regex, תקבלו שגיאה של 'תנאי לא חוקי' כי הביטוי כוללת את המירכאות הכפולות: 
request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"
 הפתרון הוא להחליף את המירכאות הכפולות המבוססות על ASCII במקבילות שלהן ב-Unicode, \u0022. לדוגמה, הביטוי הבא תקין ומפיק את התוצאה הצפויה: 
request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"