מדיניות FlowCallout

מדיניות ניתנת להרחבה

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

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

משתמשים במדיניות FlowCallout כדי לבצע קריאה ל-shared flow מ-proxy ל-API או מ-shared flow אחר.

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

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

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

דוגמאות

אימות מפתח API בתהליך משותף

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

ההגדרה הבאה של תהליך עבודה משותף כוללת מדיניות Verify-API-Key שמופעלת כשקוראים לתהליך העבודה המשותף ממדיניות FlowCallout ב-proxy ל-API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

המדיניות VerifyAPIKey בתהליך המשותף הקודם מאחזרת את ערך המפתח ומאמתת אותו.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

מדיניות FlowCallout הבאה, שמשמשת ב-proxy ל-API, קוראת ל-shared flow הקודם כדי לאמת את מפתח ה-API. חבילת זרימת העבודה המשותפת verify-apikey-shared (לא מוצגת כאן) מגדירה את זרימת העבודה המשותפת כמו שחבילת APIProxy מגדירה Proxy.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

העברת פרמטרים לתהליך עבודה משותף

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

  1. המדיניות String-Handler FlowCallout קוראת ל-Shared Flow, ומעבירה פרמטרים שמציינים את המשתנה לאחסון הפלט של ה-Shared Flow, את הפעולה של ה-Shared Flow שבה צריך להשתמש ואת הקלט שבו צריך להשתמש (כאן, מחרוזת מילולית, אבל יכול להיות שזה גם משתנה של Flow). רכיבי Parameter מציינים את השמות והערכים של משתנים ליצירה בזמן ריצה. הזרימה המשותפת יכולה לאחזר את המשתנים האלה כדי להשתמש בהם בקוד שלה.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="operations">concatenate tolowercase</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

  2. הזרימה המשותפת default הבאה כוללת מדיניות של SharedStringFunctions JavaScript שמופעלת כשקוראים לזרימה המשותפת ממדיניות FlowCallout.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
  <Step>
    <Name>SharedStringFunctions</Name>
  </Step>
</SharedFlow>

  3. בתהליך המשותף, מדיניות ה-JavaScript‏ SharedStringFunctions הבאה מציינת את קובץ ה-JavaScript‏ SharedStringFunctions.js עם הקוד להפעלה.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
  <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
  <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
</Javascript>

  4. קוד ה-JavaScript הבא, SharedStringFunctions.js, מופעל ממדיניות JavaScript‏ SharedStringFunctions. הסקריפט הזה מאחזר ערכים ממשתנים שנוצרו מרכיבי מדיניות FlowCallout Parameter.

    // Input value from the calling API proxy.
var handledString = context.getVariable("input");
// Variable to use for output from this script.
var outputVariable = context.getVariable("outputVariable");
// A space-separated list of things to do to the input string.
// Convert to lower case to handle unintentional capitals in configuration.
var operation = context.getVariable("operations").toLowerCase();

// If "lowercase" was given as an operation, convert the input to lowercase.
if (operation.includes("tolowercase")) {
    handledString = handledString.toLowerCase();
}

// If "concatenate" was given as an operation, concatenate the input.
if (operation.includes("concatenate")) {
    handledString = handledString.replace(/\s+/g, '');
}
// Assign the resulting string to the output variable specified by
// the calling API proxy.
context.setVariable(outputVariable, handledString);
  5. הביצוע חוזר ממדיניות JavaScript, אל ה-Shared Flow, ואז אל FlowCalloutהמדיניות ב-proxy ל-API המקורי.

הפניה לרכיב

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

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

מאפיינים של <FlowCallout>

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

מאפיין תיאור ברירת מחדל נוכחות
name

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

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

הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף:

 FALSE אופציונלי
enabled

מגדירים את המדיניות למצב true כדי לאכוף אותה.

מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 TRUE אופציונלי
async

המאפיין הזה הוצא משימוש.

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

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

אלמנט <SharedFlowBundle>

מציין את השם של התהליך המשותף שרוצים להפעיל. הערך של האלמנט הזה צריך להיות זהה לערך של מאפיין השם של אלמנט היעד <SharedFlowBundle>.

<SharedFlowBundle/>

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

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג לא רלוונטי

מאפיינים

אין.

אלמנט <Parameter>

מציין פרמטר וערך (או מקור ערך) להעברה כמשתנה לזרימה המשותפת שמופעלת על ידי המדיניות הזו.

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

פרמטרים של FlowCallout גלויים רק במהלך ההפעלה של התהליך המשותף.

תחביר

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

<!-- A literal value in an attribute. -->
<Parameter name="parameter-name" value='parameter-value' />
<!-- A reference to a variable in an attribute. -->
<Parameter name="parameter-name" ref='source-variable-name' />
<!-- A literal value in the element content. -->
<Parameter name="parameter-name">parameter-value</Parameter>
<!-- A reference to an attribute in the element content. -->
<Parameter name="parameter-name">{source-variable-name}</Parameter>

דוגמה

המדיניות הזו String-Handler FlowCallout מעבירה פרמטרים שמציינים איפה לאחסן את הפלט של התהליך המשותף ואיזה קלט להשתמש. רכיבי Parameter מציינים את השמות והערכים של משתנים שייווצרו בזמן הריצה. הזרימה המשותפת יכולה לאחזר את המשתנים האלה כדי להשתמש בהם בקוד שלה.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג לא רלוונטי

מאפיינים

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

המשתנה שמכיל את הערך שבו רוצים להשתמש בזמן הריצה. אם מציינים ערך מילולי לשימוש, צריך להשמיט את המאפיין הזה.

 ללא אופציונלי String
value הערך שבו יש להשתמש במשתנה של זמן הריצה שנוצר באמצעות הפרמטר הזה. לא מציינים את המאפיין הזה אם מציינים את שם המשתנה שצריך להיות מקור הערך. ללא אופציונלי String

אלמנט <Parameters>

מציין את קבוצת הרכיבים <Parameter> שיועברו כמשתנים לזרימה המשותפת שהמדיניות הזו קוראת לה.

תחביר

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

מאפיינים

אין.

סכימות

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

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

משתנה תיאור

apigee.edge.sharedflow.name

היקף ההרשאות: במהלך הביצוע של התהליך המשותף
סוג: מחרוזת
הרשאה: קריאה

הערך של מאפיין השם של התהליך המשותף.

apigee.edge.flowhook.name

היקף: במהלך הביצוע של התהליך המשותף שמצורף לנקודת ההתחברות של התהליך.
סוג: מחרוזת
הרשאה: קריאה

השם של ה-hook של התהליך.

הפניה לשגיאה

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

שגיאות זמן ריצה

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

קוד תקלה סטטוס HTTP מטרה תיקון
flow.SharedFlowNotFound 500 הזרימה המשותפת לא קיימת, או שהיא קיימת אבל לא נפרסה.

שגיאות בהטמעה

לא רלוונטי

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