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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

וידאו

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

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

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

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

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

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

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

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

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

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

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

• זרימות מותנות יכולות להפנות למשתני זרימה כדי לכוון את זרימת ה-API דרך Apigee, בדומה לאופן שבו פועלת הצהרת switch בתכנות.

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

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

משתני 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, שהוא אחד מהמשתנים המובנים של Apigee.

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

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

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

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

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

הערה: היקפי המשתנים של כל המשתנים המובנים של Apigee מפורטים בהפניה למשתני Flow.

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

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

.

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

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

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

הפניה למשתני תהליך

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

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

לדוגמה, approval.code ו-approval.status יכולים להתייחס שניהם לתכונת אישור בתהליך.

מערכת 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
• מדיניות JavaScript

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

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

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

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

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

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

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

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

בדוגמה הבאה, מדיניות ExtractVariables מנתחת הודעת תגובה ומאחסנת נתונים ספציפיים שנלקחו מהתגובה. המדיניות יוצרת שני משתנים מותאמים אישית, 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 שמופעל ב-Apigee יש גישה ישירה למשתני זרימת הנתונים של ה-proxy.

הערה: אפשר לקרוא ל-JavaScript משרת proxy באמצעות מדיניות JavaScript.

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

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

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

מה חשוב לזכור

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

• חלק מהמשתנים out-of-the-box מופעלים ומאוכלסים באופן אוטומטי על ידי ה-proxy עצמו. המשתנים האלה מתועדים במאמר בנושא משתני זרימה.
• אתם יכולים ליצור משתנים מותאמים אישית שזמינים לשימוש בתהליך של השרת הפרוקסי. אפשר ליצור משתנים באמצעות כללי מדיניות כמו AssignMessage policy ו-JavaScript policy.
• למשתנים יש היקף. לדוגמה, חלק מהמשתנים מאוכלסים אוטומטית כשהפרוקסי הראשון מקבל בקשה מאפליקציה. משתנים אחרים מאוכלסים בפלח של זרימת התגובה של הפרוקסי. משתני התגובה האלה לא מוגדרים עד שפלח התגובה מופעל.
• כשמפעילים מדיניות, אפשר ליצור משתנים ספציפיים למדיניות ולאכלס אותם. במסמכי התיעוד של כל מדיניות מפורטים כל המשתנים הרלוונטיים הספציפיים למדיניות.
• בדרך כלל, זרימות מותנות מעריכות משתנה אחד או יותר. כדי ליצור תהליכים מותנים, צריך להבין את המשתנים.
• הרבה כללי מדיניות משתמשים במשתנים כקלט או כפלט. יכול להיות שמשתנה שנוצר על ידי מדיניות אחת ישמש מאוחר יותר מדיניות אחרת.

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

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

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