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

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

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

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

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

וידאו

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

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

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

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

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

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

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

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

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

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

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

• Conditional flows יכולים להפנות למשתני flow כדי לכוון את ה-flow של 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 כשניגשים למשתנה לא מוגדר. לפרטים נוספים, אפשר לעיין בדפי העזר בנושא מדיניות

.

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

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

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

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

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

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

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

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

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

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

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