שימוש במשתני זרימה

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

מבחינה מושגית, משתני זרימה הם אובייקטים שאפשר לגשת אליהם מתוך המדיניות או כלי השירות (כמו הכלי Trace tool). הם מאפשרים לכם לשמור את המצב שמשויך לעסקת API שעובדה על ידי Apigee Edge.

מהם משתני Flow?

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

  • כתובת ה-IP, הכותרות, נתיב כתובת ה-URL והמטען הייעודי (payload) שנשלחו מהאפליקציה ששולחת את הבקשה
  • פרטי המערכת, כמו התאריך והשעה שבהם Edge מקבל בקשה
  • נתונים שמתקבלים כשמדיניות מופעלת. לדוגמה, אחרי שמדיניות שמאמתת אסימון OAuth מופעלת, Edge יוצר משתני זרימה שמכילים מידע כמו השם של האפליקציה ששולחת את הבקשה.
  • מידע על התגובה ממערכת היעד

חלק מהמשתנים הם 'מוכללים' ב-Edge ומאוכלסים באופן אוטומטי בכל פעם שמתקבלת בקשת API. הם זמינים לאורך כל העסקה ב-API. אפשר גם ליצור משתנים מותאמים אישית משלכם באמצעות כללי מדיניות כמו AssignMessage policy, או בקוד JavaScript,‏ Node.js ו-Java.

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

איך משתמשים במשתני זרימה?

משתני זרימה משמשים במדיניות ובזרימות מותנות:

  • מדיניות יכולה לאחזר מצב ממשתני זרימה ולהשתמש בהם כדי לבצע את הפעולות שלה.

    לדוגמה, מדיניות VerifyJWT יכולה לאחזר את הטוקן לאימות ממשתנה של זרימת נתונים ואז לבצע את האימות שלו. דוגמה נוספת: מדיניות JavaScript יכולה לאחזר משתני זרימה ולקודד את הנתונים שכלולים במשתנים האלה.

  • Conditional flows יכולים להפנות למשתני flow כדי לכוון את ה-flow של API דרך Edge, בדומה לאופן שבו פועלת הצהרת switch בתכנות.

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

עכשיו נראה דוגמאות לשימוש במשתנים בכל אחד מההקשרים האלה.

משתני Flow במדיניות

חלק מכללי המדיניות מקבלים משתני זרימה כקלט.

לדוגמה, מדיניות AssignMessage הבאה לוקחת את הערך של משתנה הזרימה client.ip ומציבה אותו בכותרת בקשה שנקראת My-Client-IP. אם מוסיפים את המדיניות הזו לזרימת הבקשה, היא מגדירה כותרת שמועברת ליעד העורפי. אם ההגדרה מבוצעת בתהליך התגובה, הכותרת נשלחת בחזרה לאפליקציית הלקוח.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

דוגמה נוספת: כשמדיניות של מכסת שימוש מופעלת, כמה משתני זרימה מאוכלסים בערכים שקשורים למדיניות. אחד מהמשתנים האלה נקרא ratelimit.my-quota-policy.used.count (כאשר my-quota-policy הוא שם מדיניות הקצאה שמעניינת אתכם).

אחר כך תוכלו להפעיל זרימת נתונים מותנית שאומרת: "אם מספר המכסות הנוכחי נמוך מ-50% מהמקסימום, והשעה היא בין 9:00 ל-17:00, צריך לאכוף מכסה אחרת". יכול להיות שהתנאי הזה יהיה תלוי בערך של מכסת השימוש הנוכחית ובמשתנה של זרימת נתונים שנקרא system.time, שהוא אחד מהמשתנים המובנים של Edge.

משתני תהליך בתהליכים מותנים

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

הנה תהליך מותנה שמעריך את הערך של המשתנה request.verb בשלב של תהליך proxy. במקרה הזה, אם פועל הפעולה של הבקשה הוא POST, מופעלת מדיניות VerifyAPIKey. זו תבנית נפוצה שמשמשת בהגדרות של שרתי proxy ל-API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

עכשיו אתם בטח שואלים את עצמכם מאיפה מגיעים משתנים כמו request.verb,‏ client.ip ו-system.time. מתי הם מופעלים ומאוכלסים בערך? כדי להבין מתי משתנים נוצרים ומתי הם זמינים לכם, אפשר לעיין במאמר הסבר על היקף משתני הזרימה.

משתני Flow בקוד JavaScript שמופעל באמצעות מדיניות JavaScript

באמצעות מדיניות JavaScript, אפשר להריץ קוד JavaScript מתוך ההקשר של זרימת proxy ל-API. קוד ה-JavaScript שמופעל על ידי המדיניות הזו משתמש ב-JavaScript object model של Apigee, שמאפשר לקוד המותאם אישית שלכם לגשת לאובייקטים של בקשות, תגובות והקשר שמשויכים לזרימת ה-proxy ל-API שבה הקוד מופעל. לדוגמה, הקוד הזה מגדיר כותרת תגובה עם הערך שמתקבל מהמשתנה target.name של זרימת העבודה.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

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

משתני זרימה בקוד Node.js

אם תדרשו את המודול apigee-access, תוכלו להגדיר משתני זרימה ולגשת אליהם מתוך קוד Node.js שנפרס ב-Edge.

הנה דוגמה פשוטה שבה משתנה בשם custom.foo מוגדר לערך Bar. אחרי שמגדירים את המשתנה החדש, הוא זמין לכל כללי המדיניות או לקוד אחר שמופיעים בתהליך של ה-proxy אחרי שהקוד של Node.js מופעל.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

מידע נוסף על שימוש ב-apigee-access לעבודה עם משתנים זמין במאמר גישה למשתני זרימה ב-Node.js.

הסבר על היקף משתני זרימה

המשתנה scope קשור לזרימה או ל'מחזור החיים' הכולל של קריאה ל-proxy ל-API.

הדמיה של זרימת proxy ל-API

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

האיור הבא ממחיש את רצף התהליכים הזה. שימו לב שהזרימות מורכבות מארבעה פלחים עיקריים: בקשה של ProxyEndpoint,‏ בקשה של TargetEndpoint,‏ תגובה של TargetEndpoint ותגובה של ProxyEndpoint.

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

איך היקף המשתנה קשור לזרימת ה-proxy

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

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

בטבלה הבאה מפורטים כל ההיקפים של המשתנים ומצוין מתי הם הופכים לזמינים בתהליך של ה-proxy.

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

לדוגמה, יש משתנה מובנה של Edge שנקרא client.ip. המשתנה הזה הוא בהיקף proxy request. השדה הזה מאוכלס אוטומטית בכתובת ה-IP של הלקוח שקרא ל-Proxy. המשתנה מאוכלס כשבקשה מגיעה לראשונה ל-ProxyEndpoint, והוא נשאר זמין לאורך כל מחזור החיים של תהליך ה-proxy.

יש עוד משתנה מובנה בשם target.url. ההיקף של המשתנה הזה הוא target request. הוא מאוכלס בפלח הבקשה TargetEndpoint עם כתובת ה-URL של הבקשה שנשלחה ליעד הקצה העורפי. אם תנסו לגשת אל target.url בפלח הבקשה ProxyEndpoint, תקבלו ערך NULL. אם מנסים להגדיר את המשתנה הזה לפני שהוא נמצא בהיקף, ה-proxy לא עושה כלום – הוא לא יוצר שגיאה ולא מגדיר את המשתנה.

הנה דוגמה פשוטה שממחישה איך כדאי לחשוב על היקף המשתנים. נניח שרוצים להעתיק את כל התוכן של אובייקט בקשה (כותרות, פרמטרים, גוף) ולהקצות אותו למטען הייעודי (payload) של התשובה כדי לשלוח אותו בחזרה לאפליקציה שביצעה את הקריאה. אפשר להשתמש במדיניות AssignMessage למשימה הזו. קוד המדיניות נראה כך:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

המדיניות הזו פשוט מעתיקה את אובייקט request ומקצה אותו לאובייקט response. אבל איפה צריך למקם את המדיניות הזו בתהליך של שרת ה-proxy? התשובה היא שצריך למקם אותו בתגובה של TargetEndpoint, כי ההיקף של משתנה התגובה הוא target response.

הפניה למשתני זרימה

כל המשתנים המובנים ב-Apigee Edge פועלים בהתאם למוסכמת מתן השמות של סימון נקודות. המוסכמה הזו מקלה על קביעת המטרה של המשתנה. לדוגמה system.time.hour ו-request.content.

ב-Apigee יש קידומות שונות שמשמשות לארגון משתנים רלוונטיים בצורה מתאימה. הקידומות האלה כוללות:

  • request
  • response
  • system
  • target

כדי להפנות למשתנה במדיניות, צריך להוסיף אותו בין סוגריים מסולסלים. לדוגמה, מדיניות AssignMessage הבאה לוקחת את הערך של המשתנה client.ip ומציבה אותו בכותרת בקשה שנקראת Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

בזרימות מותנות, אין צורך בסוגריים המסולסלים. בדוגמה הבאה של תנאי, המערכת מעריכה את המשתנה request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

אפשר גם להפנות למשתני זרימה בקוד JavaScript ו-Java. מידע נוסף זמין בדפים הבאים:

סוג הנתונים של משתני התהליך

לכל מאפיין של משתנה זרימה יש סוג נתונים מוגדר היטב, כמו String,‏ Long,‏ Integer,‏ Boolean או Collection. אפשר למצוא את סוגי הנתונים שמפורטים בהפניה למשתני זרימה. לגבי משתנים שנוצרו על ידי מדיניות, אפשר לעיין בנושא הספציפי של הפניה למדיניות כדי לקבל מידע על סוג הנתונים.

המשתנים שיוצרים באופן ידני מקבלים את הסוג שהוגדר להם בזמן היצירה, והם תלויים בסוגי הערכים שמותרים. לדוגמה, משתנים שנוצרו בקוד Node.js מוגבלים לערכים Number,‏ String,‏ Boolean,‏ null או undefined.

שימוש במשתני זרימה במדיניות

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

כשעובדים עם שרתי proxy ומדיניות, חשוב לעיין בהפניה למדיניות כדי לגלות אילו משתנים נוצרים ומה השימוש שלהם. לדוגמה, Quota policy יוצרת קבוצה של משתנים שמכילים מידע על מכסות ומגבלות, זמן תפוגה וכו'.

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

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

בדוגמה הבאה, הרכיב Extract Variables מנתח הודעת תגובה ומאחסן נתונים ספציפיים שנלקחו מהתגובה. המדיניות יוצרת שני משתנים מותאמים אישית, geocoderesponse.latitude ו-geocoderesponse.longitude, ומקצה להם ערכים.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

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

עבודה עם משתני זרימה בקוד JavaScript

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

כדי לגשת למשתנים בקוד JavaScript, קוראים לשיטות getter/setter בכל אחד מהאובייקטים הבאים:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

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

האובייקט context תואם למשתנים שזמינים 'באופן גלובלי', כמו משתני מערכת. לדוגמה, אפשר להפעיל את הפונקציה getVariable() באובייקט context כדי לקבל את השנה הנוכחית:

var year = context.getVariable('system.time.year');

באופן דומה, אפשר לקרוא ל-setVariable() כדי להגדיר את הערך של משתנה מותאם אישית או של כל משתנה ניתן לכתיבה שמוגדר כברירת מחדל. בדוגמה הזו אנחנו יוצרים משתנה מותאם אישית בשם organization.name.myorg ומקצים לו ערך.

var org = context.setVariable('organization.name.myorg', value);

מכיוון שהמשתנה הזה נוצר באמצעות האובייקט context, הוא יהיה זמין לכל פלחי התנועה (במילים אחרות, זה כמו ליצור משתנה גלובלי).

אפשר גם לקבל או להגדיר משתני זרימה של שרת proxy בקוד Java שמריצים באמצעות מדיניות JavaCallout.

גישה למשתני זרימה באפליקציות Node.js

אפשר לקבל, להגדיר ולמחוק משתני זרימה מקוד Node.js שנפרס ב-Edge. כל מה שצריך לעשות הוא להשתמש בפונקציה require כדי להוסיף את המודול apigee-access לקוד. פרטים נוספים זמינים במאמר בנושא גישה למשתני זרימה ב-Node.js.

מה חשוב לזכור

כמה דברים חשובים שכדאי לזכור לגבי משתני זרימה:

  • חלק מהמשתנים 'מוכנים לשימוש' מופעלים ומאוכלסים באופן אוטומטי על ידי ה-proxy עצמו. המשתנים האלה מתועדים במאמר בנושא משתני זרימה.
  • אתם יכולים ליצור משתנים מותאמים אישית שזמינים לשימוש בתהליך של השרת הפרוקסי. אפשר ליצור משתנים באמצעות כללי מדיניות כמו AssignMessage policy ו-JavaScript policy, וגם בקוד Node.js.
  • למשתנים יש היקף. לדוגמה, חלק מהמשתנים מאוכלסים אוטומטית כשהפרוקסי הראשון מקבל בקשה מאפליקציה. משתנים אחרים מאוכלסים בפלח של זרימת התגובה של הפרוקסי. משתני התגובה האלה לא מוגדרים עד שפלח התגובה מופעל.
  • כשמפעילים מדיניות, אפשר ליצור משתנים ספציפיים למדיניות ולאכלס אותם. במסמכי התיעוד של כל מדיניות מפורטים כל המשתנים הרלוונטיים הספציפיים למדיניות.
  • בדרך כלל, זרימות מותנות מעריכות משתנה אחד או יותר. כדי ליצור תהליכים מותנים, צריך להבין את המשתנים.
  • הרבה כללי מדיניות משתמשים במשתנים כקלט או כפלט. יכול להיות שמשתנה שנוצר על ידי מדיניות אחת ישמש מאוחר יותר מדיניות אחרת.
  • אפשר לקבל ולהגדיר הרבה משתני זרימה מתוך Node.js באמצעות JavaScript רגיל (ומודל האובייקטים של JavaScript שלנו) או באמצעות מדיניות JavaCallout, שמבצעת קוד ב-Edge.

דוגמאות קוד קשורות

דוגמאות ל-proxy ל-API זמינות ב-GitHub וקל להוריד אותן ולהשתמש בהן. במאמר שימוש בשרתי proxy לדוגמה של API מפורט מידע על הורדה ושימוש בדוגמאות. ברשימת הדוגמאות מפורטות דוגמאות ל-API Proxy והסבר על הפעולות שלהן.

דוגמאות לפרוקסי שכוללות שימוש במשתנים ועיבוד משתנים:

  • ‫variables – הדגמה של אופן החילוץ וההגדרה של משתנים על סמך התוכן של הודעות JSON ו-XML.
  • ‫ policy-mashup-cookbook – אפליקציה מלאה שמשתמשת בהרכבת מדיניות כדי לקרוא לשני ממשקי API ציבוריים, משלבת את התוצאות ומפיקה תגובה מועשרת לאפליקציית הלקוח. מידע נוסף על הדוגמה הזו זמין במאמר שימוש בהרכבת מדיניות.
  • ‫conditional-policy – הטמעה של אכיפת מדיניות מותנית פשוטה על סמך ערכי משתנים.

נושאים קשורים

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