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

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

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

וידאו

בסרטון הבא מוסבר על משתני תהליך:

מהם משתני תהליך?

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

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

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

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

איך משתמשים במשתני תהליך?

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

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

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

• תהליכים מותנים יכולים להפנות למשתני תהליך כדי לנתב את התהליך של ממשק API דרך Edge, בדומה לאופן שבו משפט switch פועל בתכנות.

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

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

משתני תהליך במדיניות

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

לדוגמה, מדיניות 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. מתי הם נוצרים ומאוכלסים בערך? כדי להבין מתי נוצרים משתנים ומתי הם זמינים, קראו את המאמר הסבר על היקף משתני הזרימה.

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

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

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

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

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

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

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

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

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

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

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

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

מה חשוב לזכור

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

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

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

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

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

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

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

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