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

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

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

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

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

וידאו

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

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

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

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

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

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

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

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

משתני Flow משמשים במדיניות ובתנאים של Flow:

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

  לדוגמה, מדיניות 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.

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

Conditional flows evaluate flow variables and enable proxies to behave dynamically. בדרך כלל משתמשים בתנאים כדי לשנות את ההתנהגות של זרימות, שלבים וכללי ניתוב.

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

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

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

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

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

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