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

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

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

וידאו

בסרטון הבא מוצג מבוא למשתני זרימה:

מהם משתני זרימה?

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

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

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

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

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

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

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

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

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

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

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

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

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

לדוגמה, המדיניות להקצאת הודעה הבאה לוקחת את הערך של משתנה הזרימה 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% מהערך המקסימלי, והוא בין 09:00 ל-17:00, יש לאכוף מכסה שונה". התנאי הזה עשוי להיות תלוי בערך של מספר המכסות הנוכחי ובמשתנה זרימה שנקרא system.time, שהוא אחד מהמשתנים המובנים של Edge.

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

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

כאן מוצג תהליך מותנה שמעריך את הערך של המשתנה request.verb בשלב בתהליך של שרת ה-proxy. במקרה כזה, אם פועל הבקשה הוא POST, המערכת מפעילה את VerifyAPIKey policy. זהו דפוס נפוץ המשמש בהגדרות של שרת 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? מתי הם יוצרים אובייקט ומאוכלסים בערך? במאמר הסבר על ההיקף של משתני הזרימה מוסבר מתי הם נוצרים ומתי הם זמינים.

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

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

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

השיטה הזו של השימוש ב-JavaScript כדי לקרוא ולהגדיר משתנים דומה לעבודה שאפשר לבצע באמצעות המדיניות AssignedMessage (כפי שהוצגה קודם). זו רק דרך נוספת לבצע את אותם פעולות ב-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.

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

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

• עבודה עם משתנים ב-JavaScript
• גישה למשתני זרימה ב-Node.js
• מדיניות JavaScript

סוג הנתונים של משתני הזרימה

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

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

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

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

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

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

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

בדוגמה הבאה, התכונה 'חילוץ משתנים' מנתחת הודעת תגובה ומאחסנת נתונים ספציפיים שנלקחו מהתגובה. המדיניות יוצרת שני משתנים מותאמים אישית, 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, כפי שהוסבר קודם במאמר הצגת הזרימה של שרת 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. כל מה שצריך לעשות הוא "לחייב" את המודול של הגישה ל-API בקוד. פרטים נוספים זמינים במאמר גישה למשתני זרימה ב-Node.js.

מה צריך לזכור

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

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

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

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

שרתי proxy לדוגמה הכוללים שימוש במשתנים ועיבוד משתנים כוללים:

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

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

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