מדיניות AssignMessage

אתם קוראים את מאמרי העזרה של Apigee Edge.
כדאי לעיין במסמכי העזרה בנושא Apigee X. מידע

מה

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

  • הוספה של פרמטרים חדשים של טופס, כותרות או פרמטרים של שאילתה להודעה
  • העתקה של מאפיינים קיימים מהודעה אחת להודעה אחרת
  • הסרה של כותרות, פרמטרים של שאילתות, פרמטרים של טפסים ו/או מטען ייעודי (payload) של הודעה
  • הגדרה של ערך מאפיינים קיימים בהודעה

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

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

רכיב <AssignMessage>

מגדיר מדיניות AssignMessage.

ערך ברירת המחדל מידע נוסף מופיע בכרטיסייה מדיניות ברירת המחדל שבהמשך
חובה? חובה
סוג אובייקט מורכב
רכיב אב לא רלוונטי
רכיבי צאצא <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

התחביר של רכיב <AssignMessage> הוא:

תחביר

התחביר של רכיב <AssignMessage> הוא:

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <!-- All AssignMessage child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>

  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>

  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>policy_display_name</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

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

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות AssignMessage לזרימת הנתונים בממשק המשתמש של Edge:

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <ReasonPhrase/>
    <Path/>
  </Copy>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
    <Payload/>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <AssignVariable>
    <Name>name</Name>
    <Value/>
    <Ref/>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

כשמוסיפים מדיניות חדשה של AssignMessage בממשק המשתמש של Edge, התבנית מכילה stub לכל הפעולות האפשריות. בדרך כלל, בוחרים את הפעולות שרוצים לבצע באמצעות המדיניות הזו ומסירים את שאר רכיבי הצאצא. לדוגמה, אם רוצים לבצע פעולת העתקה, אפשר להשתמש ברכיב <Copy> ולהסיר את <Add>, <Remove> ורכיבי צאצא אחרים מהמדיניות כדי שהיא תהיה קריאה יותר.

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

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי נדרש

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

אפשר להשתמש ברכיב <DisplayName> כדי להוסיף תווית למדיניות בכלי לעריכת שרת proxy של ממשק המשתמש לניהול, ולהשתמש בשם אחר בשפה טבעית.
continueOnError false אופציונלי צריך להגדיר את הערך 'False' כדי להחזיר שגיאה כשהמדיניות נכשלת. זו התנהגות צפויה ברוב סוגי המדיניות. הערך של הפרמטר הוא TRUE כדי שביצוע הפעולות יתבצע גם אחרי שמדיניות תיכשל.
enabled true אופציונלי כדי לאכוף את המדיניות צריך להגדיר את הערך True. מגדירים את המדיניות כ-"false" כדי "להשבית" את המדיניות. המדיניות הזו לא תיאכף גם אם היא תצורף לתהליך.
async   false הוצא משימוש המאפיין הזה הוצא משימוש.

בטבלה הבאה מופיע תיאור כללי של רכיבי הצאצא של <AssignMessage>:

רכיב צאצא חובה? תיאור
פעולות נפוצות
<Add> אופציונלי הפעולה מוסיפה מידע לאובייקט של ההודעה שמוגדר על ידי הרכיב <AssignTo>.

‫<Add> מוסיף כותרות או פרמטרים להודעה שלא קיימים בהודעה המקורית. כדי להחליף כותרות או פרמטרים קיימים, משתמשים ברכיב <Set>.
<Copy> אופציונלי מעתין מידע מה הודעה שצוינה במאפיין source לה אובייקט הודעה שצוין ברכיב <AssignTo>.
<Remove> אופציונלי מוחק את הרכיבים שצוינו ממשתנה ההודעה שצוין ברכיב <AssignTo>.
<Set> אופציונלי הפונקציה מחליפה ערכים של מאפיינים קיימים בבקשה או בתגובה, שצוינו על ידי הרכיב <AssignTo>.

<Set> מחליף כותרות או פרמטרים שכבר קיימים בהודעה המקורית. כדי להוסיף כותרות או פרמטרים חדשים, משתמשים ברכיב <Add>.
רכיבי צאצא אחרים
<AssignTo> אופציונלי מציינת על איזו הודעה חלה מדיניות AssignMessage. יכול להיות שמדובר בבקשה או בתשובה רגילות, או בהודעה חדשה בהתאמה אישית.
<AssignVariable> אופציונלי הפונקציה מקצה ערך למשתנה של זרימת נתונים. אם המשתנה לא קיים, הפונקציה <AssignVariable> יוצרת אותו.
<IgnoreUnresolvedVariables> אופציונלי ההגדרה הזו קובעת אם העיבוד ייפסק כשנתקלים במשתנה שלא נפתר.

כל אחד מרכיבי הצאצא האלה מתואר בקטעים הבאים.

דוגמאות

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

‫1: הוספת כותרת

בדוגמה הבאה מוסיפים כותרת לבקשה באמצעות הרכיב <Add>:

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

‫2: הסרת מטען ייעודי (payload)

בדוגמה הבאה, המטען הייעודי (payload) נמחק מהתגובה באמצעות הרכיב <Remove>:

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

‫3: שינוי התשובה

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

<AssignMessage name="modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" type="response"></AssignTo>
</AssignMessage>

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

בדוגמה הזו, שם המשתנה לא מופיע ברכיב <AssignTo>, והערך type מוגדר כ-response. לכן, המדיניות הזו משנה את אובייקט התגובה שמוחזר על ידי שרת היעד.

כותרת ה-HTTP שנוספת להודעת התגובה על ידי המדיניות הזו נגזרת ממשתנה שאוכלס על ידי מדיניות LookupCache. לכן, הודעת התגובה ששונתה על ידי מדיניות Assign Message הזו מכילה כותרת HTTP שמציינת אם התוצאות נמשכו מהמטמון או לא. הגדרת כותרות בתגובה יכולה להיות שימושית לניפוי באגים ולפתרון בעיות.

‫4: הגדרת תוכן דינמי

אתם יכולים להשתמש בפעולה Assign Message כדי להטמיע תוכן דינמי במטען הייעודי (payload) של הודעות תגובה ובקשה.

כדי להטמיע משתני Edge Flow במטען ייעודי (payload) של XML, צריך להוסיף את המשתנה המיועד בסוגריים מסולסלים, כך: {prefix.name}.

בדוגמה הבאה מוטמע הערך של משתנה הזרימה של כותרת ה-HTTP‏ user-agent באלמנט XML שנקרא User-agent:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

במטענים ייעודיים (payloads) בפורמט JSON, אפשר להוסיף משתנים באמצעות המאפיינים variablePrefix ו-variableSuffix עם תווי תיחום, כמו בדוגמה הבאה:

<AssignMessage name="set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

רשימה מלאה של משתני התהליך זמינה במאמר חומר עזר בנושא משתני תהליך.

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

‫5: הסרת פרמטר של שאילתה

בדוגמה הבאה, פרמטר השאילתה apikey מוסר מהבקשה:

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

‫6: הגדרה או קבלת משתנים

בדוגמה הבאה נעשה שימוש בשלוש מדיניות של הקצאת הודעות:

  1. יוצר שלושה משתני זרימה בבקשה, עם ערכים סטטיים
  2. קבלת משתני התהליך באופן דינמי במדיניות השנייה בתהליך הבקשה
  3. הגדרתם במטען הייעודי (payload) של התגובה
<!-- Policy #1: Set variables in the request -->
<AssignMessage continueOnError="false" enabled="true" name="set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

במדיניות הראשונה, הרכיב <AssignVariable> יוצר ומגדיר שלוש משתנים בבקשה. כל רכיב <Name> מציין שם משתנה, וכל רכיב <Value> מציין את הערך.

המדיניות השנייה משתמשת ברכיב <AssignVariable> כדי לקרוא את הערכים ויוצרת שלושה משתנים חדשים:

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

במדיניות השנייה, הרכיב <Ref> מפנה למשתנה המקור, והרכיבים <Name> מציינים את השמות של המשתנים החדשים. אם אין גישה למשתנה שאליו מפנה הרכיב <Ref>, אפשר להשתמש בערך שצוין ברכיב <Value>.

כדי לנסות את קבוצת המדיניות הזו:

  1. מוסיפים את מדיניות מספר 1 ומדיניות מספר 2 לתהליך הבקשה. חשוב להקפיד להציב את מדיניות מספר 1 לפני מדיניות מספר 2.
  2. מוסיפים את המדיניות השלישית בתהליך התגובה.
  3. המדיניות השלישית משתמשת ברכיב <Set> כדי להוסיף את המשתנים לתשובה. ‫ בדוגמה הבאה מוצג מטען ייעודי (payload) של XML בתגובה ש-Edge מחזיר ללקוח: 
    <!-- Policy #3: Add variables to the response -->
<AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
  <DisplayName>put-em-in-the-payload</DisplayName>
  <Set>
    <Payload contentType="application/xml">
      <wrapper>
        <secret>{secret}</secret>
        <config>
          <environment>{environment}</environment>
          <protocol>{protocol}</protocol>
        </config>
      </wrapper>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

    הערה: התחביר לגישה למשתני זרימה ב-<Set> הוא הוספת סוגריים מסולסלים מסביב למשתנים.

    חשוב להגדיר את מאפיין contentType של רכיב <Payload> כ-application/xml.

  4. שולחים בקשה ל-API proxy, לדוגמה: 
    curl -vL https://ahamilton-eval-test.apigee.net/myproxy

    אם רוצים, אפשר להעביר את התוצאות דרך כלי כמו xmllint כדי שה-XML יוצג במבנה מעוצב:

    curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

    גוף התגובה אמור להיראות כך:

    <wrapper>
  <secret>42</secret>
  <config>
    <environment>test</environment>
    <protocol>gopher</protocol>
  </config>
</wrapper>

‫7: קבלת כותרות תגובה של קריאה לשירות

בדוגמה הבאה, נניח שמדיניות ServiceCallout נמצאת בבקשת ה-API proxy, ותגובת ה-callout מכילה כמה כותרות עם אותו שם (Set-Cookie). בהנחה שמשתנה התגובה של Service Callout הוא ברירת המחדל calloutResponse, המדיניות הבאה מקבלת את ערך הכותרת השני של Set-Cookie.

<AssignMessage continueOnError="false" enabled="true" name="get-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

{calloutResponse.header.Set-Cookie.values}

לכל רכיב צאצא בהפניה הזו יש דוגמאות נוספות. דוגמאות נוספות זמינות בדוגמה של AssignMessage ב-GitHub.

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הבן של <AssignMessage>.

<Add>

מוסיף מידע לבקשה או לתשובה, שמוגדר על ידי הרכיב <AssignTo>.

הרכיב <Add> מוסיף מאפיינים חדשים להודעה שלא קיימים בהודעה המקורית. כדי לשנות את הערכים של מאפיינים קיימים, משתמשים ברכיב <Set>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <AssignMessage>
רכיבי צאצא <FormParams>
<Headers>
<QueryParams>

התחביר של רכיב <Add> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

דוגמה 1

בדוגמה הבאה נעשה שימוש ברכיב <FormParams> כדי לקבל את הערכים של שלושה פרמטרים של מחרוזת שאילתה מהבקשה הראשונית ולהגדיר אותם כפרמטרים של טופס בבקשה של נקודת היעד:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

דוגמה 2

בדוגמה הבאה משתמשים ברכיב <Headers> כדי להוסיף את הכותרת User-Agent לבקשה של נקודת הקצה של היעד:

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 3

בדוגמה הבאה נעשה שימוש ברכיב <QueryParams> כדי להוסיף לבקשה פרמטר יחיד של שאילתה עם ערך סטטי:

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

בדוגמה הזו נעשה שימוש ב-<Add> בתהליך המקדים של הבקשה. אם בודקים את התוצאות בכלי כמו כלי המעקב, הבקשה לכתובת http://httpbin.org/get הופכת ל-http://httpbin.org/get?myParam=42.

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

<FormParams> (ילד של <Add>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <FormParam> רכיבים
רכיב אב <Add>
רכיבי צאצא <FormParam>

התחביר של רכיב <FormParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
  </Add>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוסיפים לבקשה פרמטר טופס יחיד (answer) וערך סטטי (42):

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"></AssignTo>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מקבלים את הערך של הפרמטר name של מחרוזת השאילתה ומוסיפים אותו לבקשה כפרמטר של טופס:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
</AssignMessage>

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

דוגמה 3

בדוגמה הבאה מוסיפים כמה פרמטרים של טופס לבקשה:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

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

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

%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en

אפשר להשתמש ב-<FormParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ POST
  • סוג ההודעה: בקשה
  • אחת (או שתי) מהאפשרויות הבאות:
    • נתוני טופס: מוגדר לערך כלשהו או ל-"" (המחרוזת הריקה). לדוגמה, עם curl, מוסיפים -d "" לבקשה.
    • כותרת Content-Length: הערך שמוגדר הוא 0 (אם אין נתונים בבקשה המקורית, אחרת, האורך הנוכחי בבייטים). לדוגמה, אפשר להוסיף את הפקודה curl add -H "Content-Length: 0" לבקשה.

לדוגמה:

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

כשמוסיפים את <FormParams>, Edge מגדיר את הכותרת Content-Type של הבקשה לערך application/x-www-form-urlencoded לפני שליחת ההודעה לשירות היעד.

<Headers> (ילד של <Add>)

הפעולה מוסיפה כותרות חדשות לבקשה או לתגובה שצוינו, באמצעות הרכיב <AssignTo>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <Header> רכיבים
רכיב אב <Add>
רכיבי צאצא <Header>

התחביר של רכיב <Headers> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוסיפים את הכותרת user-agent להודעת הבקשה, ומקצים את הערך של משתנה הזרימה request.user.agent לכותרת הזו.

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<QueryParams> (ילד של <Add>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <QueryParam> רכיבים
רכיב אב <Add>
רכיבי צאצא <QueryParam>

התחביר של רכיב <QueryParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוסיפים את פרמטר השאילתה myParam לבקשה ומקצים לו את הערך 42:

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

אפשר להשתמש ב-<QueryParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ GET
  • סוג ההודעה: בקשה

בנוסף, אפשר להגדיר פרמטרים של שאילתה רק כשהמאפיין type של רכיב <AssignTo> הוא הודעת בקשה. הגדרתם בתגובה לא משפיעה.

אם מגדירים במדיניות מערך ריק של פרמטרים של שאילתה (<Add><QueryParams/></Add>), המדיניות לא מוסיפה פרמטרים של שאילתה. התוצאה זהה לזו שמתקבלת כשמשמיטים את <QueryParams>.

<AssignTo>

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

  • הודעת הבקשה: request שהתקבלה על ידי שרת ה-proxy של ה-API
  • הודעת התגובה: response שהוחזרה משרת היעד
  • הודעה מותאמת אישית: אובייקט בקשה או תגובה מותאם אישית

שימו לב שבמקרים מסוימים אי אפשר לשנות את האובייקט שעליו חלה מדיניות AssignMessage. לדוגמה, אי אפשר להשתמש ב-<Add> או ב-<Set> כדי להוסיף או לשנות פרמטרים של שאילתה (<QueryParams>) או פרמטרים של טופס (<FormParams>) בתגובה. אפשר לשנות רק את הפרמטרים של השאילתה ואת הפרמטרים של הטופס בבקשה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <AssignMessage>
רכיבי צאצא ללא

אם לא מציינים את <AssignTo>, המדיניות פועלת על בקשת ברירת המחדל או על התגובה, בהתאם למקום שבו המדיניות מופעלת. אם המדיניות מופעלת בתהליך הבקשה, היא משפיעה על הודעת הבקשה. אם היא מופעלת בתהליך התגובה, המדיניות משפיעה על התגובה כברירת מחדל.

התחביר של רכיב <AssignTo> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מצוין שהיעד הוא הבקשה המקורית שתישלח לנקודת הקצה של היעד:

<AssignMessage name="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

דוגמה 2

בדוגמה הבאה נוצר אובייקט בקשה חדש:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

כשיוצרים אובייקט בקשה או תגובה חדש, הרכיבים האחרים במדיניות AssignMessage (כמו <Add>,‏ <Set> ו-<Set>) פועלים על אובייקט הבקשה החדש הזה.

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

דוגמה 3

בדוגמה הבאה נוצר אובייקט בקשה חדש בשם MyRequestObject:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>

כשיוצרים אובייקט בקשה או תגובה חדש, הרכיבים האחרים במדיניות AssignMessage (כמו <Add>,‏ <Set> ו-<Set>) פועלים על אובייקט הבקשה החדש הזה.

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

בטבלה הבאה מתוארים המאפיינים של <AssignTo>:

מאפיין תיאור חובה? סוג
createNew

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

אם הערך הוא true, המדיניות יוצרת משתנה חדש מהסוג שצוין על ידי type (request או response). אם לא מציינים את השם של המשתנה החדש, המדיניות יוצרת אובייקט חדש של בקשה או תגובה, על סמך הערך של type.

אם הערך הוא false, המדיניות מגיבה באחת משתי דרכים:

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

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

  • אם <AssignTo> נפתר להודעה, העיבוד עובר לשלב הבא.
  • אם לא ניתן לפתור את <AssignTo>, או אם הפתרון הוא לא מסוג הודעה, נוצר משתנה חדש מהסוג שצוין ב-type.
 אופציונלי בוליאני
transport

מציין את סוג התעבורה של סוג ההודעה של הבקשה או התגובה.

ערך ברירת המחדל הוא 'http' (הערך הנתמך היחיד).

 אופציונלי מחרוזת
type מציין את סוג ההודעה החדשה, אם הערך של createNew הוא true. הערכים התקינים הם request או response.

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

 אופציונלי מחרוזת

<AssignVariable>

הקצאת ערך למשתנה של יעד בתהליך (למשל, משתנה שהערך שלו מוגדר על ידי מדיניות AssignMessage). אם משתנה הזרימה לא קיים, הפונקציה <AssignVariable> יוצרת אותו.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <AssignMessage>
רכיבי צאצא <Name> (חובה)
<Ref>
<Template>
<Value>

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

  • מחרוזת מילולית: משתמשים ברכיב הצאצא <Value> כדי לציין ערך מחרוזת מילולית למשתנה של זרימת היעד.
  • משתנה של זרימת נתונים: משתמשים ברכיב הצאצא <Ref> כדי לציין את הערך של משתנה קיים של זרימת נתונים עבור משתנה היעד של זרימת הנתונים. רשימה מלאה של משתני זרימה שאפשר להשתמש בהם כמקור זמינה במאמר חומר עזר בנושא משתני זרימה.
  • תבנית הודעה: משתמשים באלמנט הצאצא <Template> כדי לציין תבנית הודעה למשתנה של זרימת היעד.

התחביר של רכיב <AssignVariable> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

משתמשים ברכיב <Ref> כדי לציין את משתנה המקור. אם המשתנה שאליו מתבצעת ההפניה באמצעות <Ref> לא נגיש, Edge משתמש בערך שצוין ברכיב <Value>. אם מגדירים את <Template>, הוא מקבל עדיפות על פני שאר רכיבי הצאצא.

דוגמה 1

בדוגמה הבאה מוגדר הערך של משתנה חדש, myvar, כערך המילולי '42':

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

דוגמה 2

בדוגמה הבאה, הערך של משתנה הזרימה request.header.user-agent מוקצה למשתנה זרימת היעד myvar, והערך של פרמטר השאילתה country מוקצה למשתנה זרימת היעד Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

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

אם משתני הזרימה myvar או Country לא קיימים, המערכת <AssignVariable> יוצרת אותם.

דוגמה 3

בדוגמה הבאה נעשה שימוש ברכיב הצאצא <Template> כדי לשרשר שתי משתני הקשר עם מחרוזת מילולית (מקף) ביניהם:

<AssignMessage name='template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

שימוש נפוץ ב-<AssignVariable> הוא הגדרת ערך ברירת מחדל לפרמטר של שאילתה, לכותרת או לערך אחר שאפשר להעביר עם הבקשה. הפעולה הזו מתבצעת באמצעות שילוב של רכיבי הצאצא <Ref> ו-<Value>. מידע נוסף זמין בדוגמאות ל-<Ref>.

<Name> (ילד של <AssignVariable>)

מציין את השם של משתנה היעד של זרימת הנתונים (למשל, המשתנה שהערך שלו מוגדר על ידי מדיניות AssignMessage). אם המשתנה שצוין ב-<AssignVariable> לא קיים, המדיניות יוצרת משתנה בשם הזה.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג מחרוזת
רכיב אב <AssignVariable>
רכיבי צאצא ללא

התחביר של רכיב <Name> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
  </AssignVariable>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, משתנה היעד הוא myvar, והוא מוגדר לערך המילולי '42':

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

אם myvar לא קיים, הפקודה <AssignVariable> יוצרת אותו.

<Ref> (ילד של <AssignVariable>)

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

הערך של <Ref> תמיד מתפרש כמשתנה של זרימת נתונים. אי אפשר לציין מחרוזת מילולית כערך. כדי להקצות ערך מחרוזת מילולי, צריך להשתמש ברכיב <Value>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <AssignVariable>
רכיבי צאצא ללא

כשמציינים משתנה של זרימת נתונים באמצעות <Ref>, צריך להשמיט את הסוגריים המסולסלים {} שבהם בדרך כלל משתמשים כדי להפנות למשתנה של זרימת נתונים. לדוגמה, כדי להגדיר את הערך של המשתנה החדש לערך של המשתנה client.host flow:

Do this (no brackets):
  <Ref>client.host</Ref>

Do NOT do this (brackets):
  <Ref>{client.host}</Ref>

כדי להגדיר ערך ברירת מחדל למשתנה של זרימת היעד, משתמשים ב-<Value> בשילוב עם <Ref>. אם משתנה הזרימה שצוין על ידי <Ref> לא קיים, אי אפשר לקרוא אותו או שהוא null,‏ Edge מקצה במקומו את הערך של <Value> למשתנה היעד של הזרימה.

התחביר של רכיב <Ref> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
  </AssignVariable>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של משתנה הזרימה request.header.user-agent מוקצה למשתנה זרימת היעד myvar, והערך של פרמטר השאילתה country מוקצה למשתנה Country:

<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

בדוגמה הזו, לא הוגדרה ב-Edge ברירת מחדל (או ערך חלופי) לאף אחת מהמטלות.

דוגמה 2

בדוגמה הבאה מוקצה הערך של משתנה הזרימה request.header.user-agent למשתנה זרימת היעד myvar, והערך של פרמטר השאילתה country מוקצה למשתנה Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

בדוגמה הזו, אם הערכים של request.header.user-agent משתנה הזרימה או של פרמטר השאילתה Country הם null, לא ניתנים לקריאה או פגומים, Edge מקצה את הערך ErrorOnCopy למשתנים החדשים.

דוגמה 3

תרחיש נפוץ לשימוש ב-<AssignVariable> הוא הגדרת ערך ברירת מחדל לפרמטר של שאילתה, לכותרת או לערך אחר שאפשר להעביר עם הבקשה. לדוגמה, אתם יוצרים שרת proxy של API למזג אוויר, שבו הבקשה מקבלת פרמטר שאילתה יחיד בשם w. הפרמטר הזה מכיל את מזהה העיר שרוצים לדעת את מזג האוויר שלה. כתובת ה-URL של הבקשה היא מהצורה הבאה:

http://myCO.com/v1/weather/forecastrss?w=city_ID

כדי להגדיר ערך ברירת מחדל ל-w, יוצרים מדיניות AssignMessage כמו בדוגמה הבאה:

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref>
    <Value>12797282</Value>
  </AssignVariable>
</AssignMessage>

בדוגמה הזו, <AssignVariable> מקבל את הערך של request.queryparam.w ומקצה אותו לעצמו. אם משתנה הזרימה הוא null, כלומר פרמטר השאילתה w הושמט מהבקשה, בדוגמה הזו נעשה שימוש בערך ברירת המחדל מהרכיב <Value>. לכן, אפשר לשלוח בקשה ל-API proxy הזה בלי הפרמטר w של השאילתה:

http://myCO.com/v1/weather/forecastrss

…ועדיין לקבל תוצאה תקינה משרת ה-proxy של ה-API.

בניגוד לשימוש ב-<Value>, הערך של <Ref> חייב להיות משתנה של זרימת נתונים, כמו מאפיין של אובייקט request,‏ response או target. הערך יכול להיות גם משתנה מותאם אישית של זרימת העבודה שיצרתם.

אם מציינים משתנה של זרימת נתונים שלא קיים עבור הערך של <Ref>, והערך של <IgnoreUnresolvedVariables> הוא true,‏ Edge יחזיר שגיאה.

<Template> (ילד של <AssignVariable>)

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

משתמשים במאפיין ref כדי לציין משתנה של זרימה שבו הערך של המשתנה הוא תבנית הודעה. לדוגמה, אפשר לאחסן תבנית הודעה כמאפיין מותאם אישית באפליקציית פיתוח. כש-Edge מזהה את אפליקציית הפיתוח אחרי שהוא מאמת את מפתח ה-API או את אסימון האבטחה (באמצעות מדיניות נוספת), רכיב ה-<AssignVariable> יכול להשתמש בתבנית ההודעה מתוך המאפיין המותאם אישית של האפליקציה, שזמין כמשתנה של זרימת הנתונים ממדיניות האבטחה. בדוגמה הבאה נניח שתבנית ההודעה זמינה במאפיין לקוח בשם message_template באפליקציית המפתחים שמבצעת את הקריאה ל-API, שבה נעשה שימוש במדיניות VerifyAPIKey כדי לאמת את מפתח ה-API של האפליקציה:

<AssignVariable ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <AssignVariable>
רכיבי צאצא ללא

התחביר של רכיב <Template> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
  </AssignVariable>
</AssignMessage>

דוגמה 1

בדוגמה הבאה נעשה שימוש בתחביר של תבניות הודעות כדי לשרשר שתי משתני הקשר עם מחרוזת מילולית (מקף) ביניהם:

<AssignMessage name='template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

דוגמה 2

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

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>

  </AssignVariable>
</AssignMessage>

דוגמה 3

בדוגמה הבאה מצוינים משתנה של זרימת נתונים וערך טקסט. במקרה הזה, אם המשתנה שאליו מתבצעת ההפניה הוא לא null, הערך הזה ישמש כתבנית. אם הערך שאליו יש הפניה הוא null, המערכת משתמשת בערך הטקסט (במקרה הזה, {system.uuid}-{messageid}) כתבנית. התבנית הזו שימושית כדי לספק ערך של 'שינוי ברירת המחדל', במקרים שבהם רוצים לשנות את ברירת המחדל של התבנית (חלק הטקסט) עם ערכים שמוגדרים באופן דינמי. לדוגמה, משפט מותנה יכול לאחזר ערך ממפת מפתח/ערך ולהגדיר את המשתנה שאליו מתייחסים לערך הזה:

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

<Value> (ילד של <AssignVariable>)

הערך של משתנה היעד של ה-Flow שמוגדר באמצעות <AssignVariable>. הערך תמיד מתפרש כמחרוזת ליטרלית. אי אפשר להשתמש במשתנה של זרימת נתונים כערך, גם אם מקיפים את הערך בסוגריים מסולסלים ({}). כדי להשתמש במשתנה של זרימת נתונים, צריך להשתמש במקום זאת ב-<Ref>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <AssignVariable>
רכיבי צאצא ללא

כשמשתמשים בו בשילוב עם הרכיב <Ref>, הערך <Value> משמש כערך ברירת המחדל (או כערך חלופי). אם לא מציינים את <Ref>, אם אי אפשר לפתור אותו או אם הוא null, המערכת משתמשת בערך של <Value>.

התחביר של רכיב <Value> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר הערך של משתנה היעד של הזרימה, myvar, לערך המילולי '42':

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מוקצה הערך של משתנה הזרימה request.header.user-agent למשתנה הזרימה myvar, והערך של פרמטר השאילתה country מוקצה למשתנה Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

אם אחת מההקצאות נכשלת, במקום זאת, <AssignVariable> מקצה את הערך ErrorOnCopy למשתנה של זרימת היעד.

<Copy>

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <AssignMessage>
רכיבי צאצא <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

התחביר של רכיב <Copy> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
    <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

דוגמה 1

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

<AssignMessage continueOnError="false" enabled="true" name="copy-1">
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1">Header value 1</Header>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_2">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_3">Form param value 1</FormParam>
    </FormParams>
    <Payload>false</Payload>
    <Path>true</Path>
    <QueryParams/>
    <ReasonPhrase>false</ReasonPhrase>
    <StatusCode>false</StatusCode>
    <Verb>false</Verb>
    <Version>false</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

לרכיב <Copy> יש את המאפיינים הבאים:

מאפיין תיאור חובה? סוג
source

מציין את אובייקט המקור של ההעתקה.

  • אם לא מציינים את source, ההודעה נחשבת להודעה פשוטה. לדוגמה, אם המדיניות נמצאת בתהליך הבקשה, מקור ברירת המחדל הוא אובייקט request. אם המדיניות נמצאת בתהליך התגובה, ברירת המחדל היא האובייקט response. אם לא מציינים את source, אפשר להשתמש בהפניה מוחלטת למשתנה של זרימת עבודה כמקור של העותק. לדוגמה, הערך יצוין כ-{request.header.user-agent}.
  • אם אי אפשר לפתור את משתנה המקור, או שהוא נפתר כסוג שאינו הודעה, <Copy> לא מגיב.
 אופציונלי מחרוזת

<FormParams> (ילד של <Copy>)

מעתיק פרמטרים של טופס מהבקשה שצוינה על ידי מאפיין source של רכיב <Copy> אל הבקשה שצוינה על ידי רכיב <AssignTo>. לרכיב הזה אין השפעה על התגובה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <FormParam> או מערך ריק
רכיב אב <Copy>
רכיבי צאצא <FormParam>

התחביר של רכיב <FormParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מועתק פרמטר טופס יחיד מהבקשה לבקשה המותאמת אישית MyCustomRequest:

<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מועתקים כל הפרמטרים של הטופס לבקשה המותאמת אישית MyCustomRequest:

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 3

בדוגמה הבאה מועתקים שלושה פרמטרים של טופס לבקשה המותאמת אישית MyCustomRequest:

<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 4

אם יש כמה פרמטרים של טופס עם אותו שם, משתמשים בתחביר הבא:

<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

בדוגמה הזו, הפונקציה מעתיקה את הערכים f1,‏ f2 ואת הערך השני של f3. אם למאפיין f3 יש רק ערך אחד, הוא לא מועתק.

אפשר להשתמש ב-<FormParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ POST
  • סוג ההודעה: תגובה
  • אחת (או שתי) מהאפשרויות הבאות:
    • נתוני טופס: מוגדר לערך כלשהו או ל-"" (המחרוזת הריקה). לדוגמה, עם curl, מוסיפים -d "" לבקשה.
    • Content-Length כותרת: מוגדר ל-0 (אם אין נתונים בבקשה המקורית, אחרת, האורך הנוכחי). לדוגמה, אפשר להוסיף את הפקודה curl add -H "Content-Length: 0" לבקשה.

כשמעתיקים את <FormParams>, ‏ <Copy> מגדיר את Content-Type של ההודעה ל-application/x-www-form-urlencoded לפני שליחת ההודעה לשירות היעד.

<Headers> (ילד של <Copy>)

מעתיק כותרות HTTP מהודעת הבקשה או התגובה שצוינה על ידי מאפיין source של אלמנט <Copy> אל הודעת הבקשה או התגובה שצוינה על ידי אלמנט <AssignTo>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <Header> או מערך ריק
רכיב אב <Copy>
רכיבי צאצא <Header>

התחביר של רכיב <Headers> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מועתקת הכותרת user-agent מהבקשה לאובייקט הבקשה המותאם אישית החדש:

<AssignMessage name="copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 2

כדי להעתיק את כל הכותרות, משתמשים ברכיב <Headers> ריק, כמו בדוגמה הבאה:

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 3

אם יש כמה כותרות עם אותו שם, צריך להשתמש בתחביר הבא:

<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

בדוגמה הזו, הפונקציה מעתיקה את הערכים h1,‏ h2 ואת הערך השני של h3. אם למאפיין h3 יש רק ערך אחד, הוא לא מועתק.

<Path> (ילד של <Copy>)

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

אם הערך הוא True, המדיניות הזו מעתיקה את הנתיב מה הודעת הבקשה שצוינה על ידי המאפיין source של הרכיב <Copy> אל הודעת הבקשה שצוינה על ידי הרכיב <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <Path> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

דוגמה 1

הדוגמה הבאה מציינת שמדיניות AssignMessage צריכה להעתיק את הנתיב מבקשת המקור לאובייקט הבקשה החדש בהתאמה אישית:

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<Path> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה

<Payload> (ילד של <Copy>)

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

אם הערך הוא true, המדיניות מעתיקה את מטען הנתונים מהההודעה שצוינה על ידי המאפיין source של הרכיב <Copy> אל ההודעה שצוינה על ידי הרכיב <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <Payload> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <Payload> מוגדר כ-true, כך שמטען הייעודי (payload) של הבקשה מועתק מהבקשה לתגובה:

<AssignMessage name="copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

<QueryParams> (ילד של <Copy>)

מעתין פרמטרים של מחרוזת שאילתה מהבקשה שצוינה על ידי מאפיין source של רכיב <Copy> אל בקשה שצוינה על ידי רכיב <AssignTo>. לרכיב הזה אין השפעה על התשובה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <QueryParam> או מערך ריק
רכיב אב <QueryParam>
רכיבי צאצא ללא

התחביר של רכיב <QueryParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מועתק פרמטר השאילתה my_param מהבקשה לאובייקט בקשה מותאם אישית חדש:

<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מועתקים כל פרמטרי השאילתה מהבקשה לאובייקט בקשה מותאם אישית חדש:

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

דוגמה 3

אם יש כמה פרמטרים של שאילתה עם אותו שם, צריך להשתמש בתחביר הבא:

<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

בדוגמה הזו, הפונקציה מעתיקה את הערכים qp1,‏ qp2 ואת הערך השני של qp3. אם למשתנה qp3 יש רק ערך אחד, הוא לא מועתק.

אפשר להשתמש ב-<QueryParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ GET
  • סוג ההודעה: בקשה

<ReasonPhrase> (ילד של <Copy>)

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

אם הערך הוא True, המדיניות הזו מעתיקה את ReasonPhrase מהתגובה שצוינה על ידי מאפיין source של רכיב <Copy> אל תגובה שצוינה על ידי רכיב <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <ReasonPhrase> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <ReasonPhrase>[false|true]</ReasonPhrase>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <ReasonPhrase> מוגדר כ-true, ולכן <Copy> מעתיק את משפט הסיבה מהתגובה שמוגדרת כברירת מחדל לאובייקט תגובה מותאם אישית:

<AssignMessage name="copy-reasonphrase-1">
  <Copy source="response">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo createNew="trie" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<ReasonPhrase> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: תגובה

<StatusCode> (ילד של <Copy>)

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

אם הערך הוא true, המדיניות מעתיקה את קוד הסטטוס מה הודעת התגובה שצוינה על ידי מאפיין source של רכיב <Copy> לה הודעת התגובה שצוינה על ידי רכיב <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <StatusCode> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <StatusCode> מוגדר כ-true, ולכן קוד הסטטוס מועתק מאובייקט התגובה שמוגדר כברירת מחדל לאובייקט תגובה חדש ומותאם אישית:

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<StatusCode> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: תגובה

אחד השימושים הנפוצים ב-<StatusCode> הוא לוודא שלתגובת ה-proxy יש את אותו סטטוס כמו לתגובה שהתקבלה מהיעד כשמאפיין createNew של <AssignTo> מוגדר כ-true.

<Verb> (ילד של <Copy>)

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

אם הערך הוא true, הפועל שנמצא במאפיין source של הרכיב <Copy> מועתק לבקשה שצוינה ברכיב <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <Verb> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <Verb> מוגדר כ-true, ולכן הפועל מועתק מהבקשה שמוגדרת כברירת מחדל לבקשה חדשה בהתאמה אישית:

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<Verb> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה

<Version> (ילד של <Copy>)

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

אם הערך הוא true, המערכת מעתיקה את גרסת ה-HTTP שנמצאת במאפיין source של האלמנט <Copy> לאובייקט שצוין באלמנט <AssignTo>.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Copy>
רכיבי צאצא ללא

התחביר של רכיב <Version> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <Version> מוגדר כ-true בבקשה, מה שגורם להעתקת הגרסה מאובייקט הבקשה שמוגדר כברירת מחדל לאובייקט בקשה חדש ומותאם אישית:

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<Version> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה

<DisplayName>

אפשר להשתמש במאפיין name כדי לתייג את המדיניות בכלי העריכה של שרת ה-proxy בממשק המשתמש לניהול, בשם שונה שנשמע טבעי יותר.

הרכיב <DisplayName> הוא משותף לכל כללי המדיניות.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי. אם משמיטים את <DisplayName>, המערכת משתמשת בערך של המאפיין name של המדיניות
סוג מחרוזת
רכיב הורה <PolicyElement>
רכיבי הצאצאים ללא

רכיב <DisplayName> כולל את התחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לאלמנט <DisplayName> אין מאפיינים או רכיבי צאצא.

<IgnoreUnresolvedVariables>

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

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <AssignMessage>
רכיבי צאצא ללא

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

ההגדרה <IgnoreUnresolvedVariables> ל-true שונה מההגדרה של continueOnError של <AssignMessage> ל-true, כי היא ספציפית להגדרה ולקבלת ערכים של משתנים. אם מגדירים את continueOnError ל-true, ‏ Edge מתעלם מכל השגיאות, ולא רק משגיאות שמתרחשות כשמשתמשים במשתנים.

התחביר של רכיב <IgnoreUnresolvedVariables> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <IgnoreUnresolvedVariables> מוגדר ל-true:

<AssignMessage name="ignoreunresolvedvariables">
  <Copy source="response">
    ...
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  </Copy>
</AssignMessage>

<Remove>

הסרת כותרות, פרמטרים של שאילתות, פרמטרים של טפסים ו/או מטען הייעודי (payload) של ההודעה מהודעה. ההודעה יכולה להיות בקשה או תגובה. כדי לציין על איזו הודעה <Remove> פועל הרכיב, משתמשים ברכיב <AssignTo>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <AssignMessage>
רכיבי צאצא <FormParams>
<Headers>
<Payload>
<QueryParams>

מקרה שימוש נפוץ ב-<Remove> הוא מחיקה של פרמטר שאילתה שמכיל מידע רגיש מאובייקט הבקשה הנכנסת, כדי למנוע את העברתו לשרת העורפי.

התחביר של רכיב <Remove> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, גוף ההודעה מוסר מהתגובה:

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

בתהליך התגובה, המדיניות הזו מסירה את גוף התגובה ומחזירה רק כותרות HTTP ללקוח.

דוגמה 2

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

<AssignMessage continueOnError="false" enabled="true" name="remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<FormParams> (ילד של <Remove>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <FormParam> או מערך ריק
רכיב אב <Remove>
רכיבי צאצא <FormParam>

התחביר של רכיב <FormParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, שלושה פרמטרים של טופס מוסרים מהבקשה:

<AssignMessage name="remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מוסרים כל הפרמטרים של הטופס מהבקשה:

<AssignMessage name="remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

דוגמה 3

אם יש כמה פרמטרים של טופס עם אותו שם, משתמשים בתחביר הבא:

<AssignMessage name="remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

בדוגמה הזו, הערכים f1,‏ f2 והערך השני של f3 מוסרים. אם יש רק ערך אחד ב-f3, הוא לא יוסר.

אפשר להשתמש ב-<FormParams> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה
  • Content-Type: "application/x-www-form-urlencoded"

<Headers> (ילד של <Remove>)

הסרה של כותרות HTTP שצוינו מהבקשה או מהתגובה, שצוינו על ידי הרכיב <AssignTo>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <Header> או מערך ריק
רכיב אב <Remove>
רכיבי צאצא <Header>

התחביר של רכיב <Headers> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הכותרת user-agent מוסרת מהבקשה:

<AssignMessage name="remove-headers-1">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 2

בדוגמה הבאה, כל הכותרות מוסרות מהבקשה:

<AssignMessage name="remove-headers-2">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 3

אם יש כמה כותרות עם אותו שם, צריך להשתמש בתחביר הבא:

<AssignMessage name="remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

בדוגמה הזו, הערכים h1,‏ h2 והערך השני של h3 מוסרים מהבקשה. אם לרכיב h3 יש רק ערך אחד, הוא לא יוסר.

<Payload> (ילד של <Remove>)

המאפיין קובע אם <Remove> מוחק את מטען הייעודי (payload) בבקשה או בתגובה, שמוגדר על ידי רכיב <AssignTo>. הערך true מוחק את מטען הייעודי (payload), והערך false לא מוחק אותו. ערך ברירת המחדל הוא false.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב אב <Remove>
רכיבי צאצא ללא

התחביר של רכיב <Payload> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הערך של <Payload> מוגדר כ-true כדי שמטען הייעודי (payload) של הבקשה יימחק:

<AssignMessage name="remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<QueryParams> (ילד של <Remove>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של רכיבי <QueryParam> או מערך ריק
רכיב אב <Remove>
רכיבי צאצא <QueryParam>

התחביר של רכיב <QueryParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוסר פרמטר שאילתה יחיד מהבקשה:

<AssignMessage name="remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 2

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

<AssignMessage name="remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 3

אם יש כמה פרמטרים של שאילתה עם אותו שם, צריך להשתמש בתחביר הבא:

<AssignMessage name="remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

בדוגמה הזו, הערכים qp1,‏ qp2 והערך השני של qp3 מוסרים מהבקשה. אם ל-qp3 יש רק ערך אחד, הוא לא יוסר.

דוגמה 4

בדוגמה הבאה, פרמטר השאילתה apikey מוסר מהבקשה:

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

אפשר להשתמש ב-<QueryParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ GET
  • סוג ההודעה: בקשה

<Set>

הפרמטר הזה מגדיר מידע בהודעת הבקשה או התגובה, שמוגדר על ידי הרכיב <AssignTo>. <Set> מחליף כותרות או פרמטרים שכבר קיימים בהודעה המקורית. כדי ליצור כותרת או פרמטר חדשים, משתמשים במקום זאת ברכיב <Add>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <AssignMessage>
רכיבי צאצא <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

התחביר של רכיב <Set> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוצג הרכיב <Set>:

<AssignMessage continueOnError="false" enabled="true" name="set-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
    <QueryParams>
      <QueryParam name="name">{request.header.name}</QueryParam>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
    <!-- <Verb>GET</Verb> -->
    <Payload contentType="text/plain">42</Payload>
    <Path/>
    <ReasonPhrase>Bad request</ReasonPhrase>
    <StatusCode>400</StatusCode>
    <Verb>POST</Verb>
    <Verb>{my_variable}</Verb>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<FormParams> (ילד של <Set>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <FormParam> רכיבים
רכיב אב <Set>
רכיבי צאצא <FormParam>

התחביר של רכיב <FormParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר פרמטר של טופס בשם myparam לערך של המשתנה request.header.myparam בבקשה חדשה ומותאמת אישית:

<AssignMessage name="set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
    <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<FormParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ POST
  • סוג ההודעה: בקשה

אם מגדירים פרמטרים ריקים של טופס במדיניות (<Add><FormParams/></Add>), המדיניות לא מוסיפה פרמטרים של טופס. זה כמו להשמיט את <FormParams>.

‫<Set> משנה את Content-Type של ההודעה ל-application/x-www-form-urlencoded לפני השליחה לנקודת היעד.

<Headers> (ילד של <Set>)

מחליף כותרות HTTP קיימות בבקשה או בתגובה, שמוגדרות על ידי הרכיב <AssignTo>.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <Header> רכיבים
רכיב אב <Set>
רכיבי צאצא <Header>

התחביר של רכיב <Headers> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הכותרת user-agent מוגדרת לערך של המשתנה request.header.user-agent:

<AssignMessage name="set-headers-1">
  <Set>
    <Headers>
      <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

אם מגדירים כותרות ריקות במדיניות (<Add><Headers/></Add>), המדיניות לא מוסיפה כותרות. התוצאה זהה לזו של השמטת <Headers>.

<Path> (ילד של <Set>)

<Payload> (ילד של <Set>)

ההגדרה מגדירה את גוף ההודעה של בקשה או תגובה, שמוגדר על ידי הרכיב <AssignTo>. המטען הייעודי יכול להיות כל סוג תוכן תקין, כמו טקסט פשוט, JSON או XML.

ערך ברירת המחדל מחרוזת ריקה
חובה? אופציונלי
סוג מחרוזת
רכיב אב <Set>
רכיבי צאצא ללא

התחביר של רכיב <Payload> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר מטען ייעודי (payload) של טקסט פשוט:

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מוגדר מטען ייעודי (payload) של JSON:

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

דוגמה 3

בדוגמה הבאה, ערכי משתנים מוכנסים למטען הייעודי (payload) על ידי הוספת סוגריים מסולסלים לשמות המשתנים:

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

בגרסאות ישנות יותר של Apigee Edge – לדוגמה, לפני גרסת הענן 16.08.17 – לא הייתה אפשרות להשתמש בסוגריים מסולסלים כדי לציין הפניות למשתנים במטענים ייעודיים (payloads) בפורמט JSON. בגרסאות האלה, היה צריך להשתמש במאפיינים variablePrefix ו-variableSuffix כדי לציין תווים של תווי הפרדה, ולהשתמש בהם כדי לתחום שמות של משתנים, כמו בדוגמה הבאה:

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

התחביר הישן הזה עדיין עובד.

דוגמה 4

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

בדוגמה הבאה נעשה שימוש בתחביר של סוגריים מסולסלים כדי להגדיר חלק מהמטען הייעודי (payload) לערך משתנה:

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

בטבלה הבאה מתוארים המאפיינים של <Payload>:

מאפיין תיאור נוכחות סוג
contentType

אם מציינים ערך, הערך של contentType מוקצה לכותרת ה-HTTP‏ Content-Type.

 אופציונלי מחרוזת
variablePrefix מציין באופן אופציונלי את התו המפריד המוביל במשתנה של זרימת נתונים. ברירת המחדל היא '{'. מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה. אופציונלי Char
variableSuffix אפשר לציין תו מפריד בסוף משתנה של זרימת נתונים. ברירת המחדל היא '}'. מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה. אופציונלי Char

<QueryParams> (ילד של <Set>)

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

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מערך של <QueryParam> רכיבים
רכיב אב <Set>
רכיבי צאצא <QueryParam>

התחביר של רכיב <QueryParams> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר פרמטר השאילתה address לערך של המשתנה request.header.address:

<AssignMessage continueOnError="false" enabled="true" name="set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

אפשר להשתמש ב-<QueryParams> רק אם מתקיימים הקריטריונים הבאים:

  • פועל HTTP: ‏ GET
  • סוג ההודעה: בקשה

אם מגדירים פרמטרים ריקים של שאילתה במדיניות (<Set><QueryParams/></Set>), המדיניות לא מגדירה פרמטרים של שאילתה. התוצאה זהה לזו שמתקבלת כשמשמיטים את <QueryParams>.

<ReasonPhrase> (ילד של <Set>)

מגדיר את משפט הסיבה בתגובה. בדרך כלל משתמשים באפשרות הזו לניפוי באגים בשילוב עם <StatusCode>. לרכיב הזה אין השפעה על בקשה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת
רכיב אב <Set>
רכיבי צאצא ללא

התחביר של רכיב <ReasonPhrase> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר משפט סיבה פשוט:

<AssignMessage name="set-reasonphrase-1">
  <Set>
    <ReasonPhrase>Bad medicine</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

דוגמה 2

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

<AssignMessage name="set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

אפשר להשתמש ב-<ReasonPhrase> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: תגובה

<StatusCode> (ילד של <Set>)

הגדרת קוד הסטטוס בתשובה. לרכיב הזה אין השפעה על בקשה.

ערך ברירת המחדל ‫'200' (כשהמאפיין createNew של <AssignTo> מוגדר כ-'true')
חובה? אופציונלי
סוג מחרוזת או variable
רכיב אב <Set>
רכיבי צאצא ללא

התחביר של רכיב <StatusCode> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר קוד סטטוס פשוט:

<AssignMessage name="set-statuscode-1">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

דוגמה 2

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

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

אפשר להשתמש ב-<StatusCode> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: תגובה

<Verb> (ילד של <Set>)

מגדיר את פועל ה-HTTP בבקשה. לרכיב הזה אין השפעה על התשובה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת או variable
רכיב אב <Set>
רכיבי צאצא ללא

התחביר של רכיב <Verb> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוגדר פועל פשוט בבקשה:

<AssignMessage name="set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

דוגמה 2

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

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

<AssignMessage name="set-verb-2">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

אפשר להשתמש ב-<Verb> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה

<Version> (ילד של <Set>)

הגדרת גרסת ה-HTTP בבקשה. לרכיב הזה אין השפעה על התשובה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מחרוזת או variable
רכיב אב <Set>
רכיבי צאצא ללא

התחביר של רכיב <Version> הוא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, מספר הגרסה מוגדר כ-1.1:

<AssignMessage name="set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

דוגמה 2

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

<AssignMessage name="set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

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

אפשר להשתמש ב-<Version> רק אם מתקיימים הקריטריונים הבאים:

  • סוג ההודעה: בקשה

יצירת הודעות בקשה בהתאמה אישית

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

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

כדי ליצור הודעת בקשה בהתאמה אישית, משתמשים ברכיב <AssignTo> במדיניות AssignMessage. מגדירים את createNew לערך true ומציינים את שם ההודעה החדשה בגוף הרכיב, כמו בדוגמה הבאה:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

כברירת מחדל, Edge לא עושה כלום עם הודעת הבקשה המותאמת אישית. אחרי שיוצרים את הבקשה, Edge ממשיך בתהליך עם הבקשה המקורית. כדי להשתמש בבקשה מותאמת אישית, מוסיפים לממשק ה-proxy מדיניות כמו ServiceCallout policy, שיכולה להעביר את הבקשה המותאמת אישית לשירות חיצוני.

בדוגמאות הבאות מוצגות הודעות בקשה בהתאמה אישית:

דוגמה 1

בדוגמה הבאה נוצר אובייקט בקשה בהתאמה אישית עם Assign Message:

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Copy>
    <Headers>
     <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

בדוגמה הזו:

  • יוצר אובייקט חדש של הודעת בקשה בשם MyCustomRequest.
  • ב-MyCustomRequest, המדיניות הזו:
    • מעתין את הערך של כותרת ה-HTTP‏ user-agent מהבקשה הנכנסת להודעה החדשה. מכיוון שהפונקציה <Copy> משתמשת בהפניה מוחלטת למשתנה של זרימת הנתונים user-agent, אין צורך לציין את המאפיין source לפונקציה <Copy>.
    • מגדיר את פרמטר השאילתה address בהודעה המותאמת אישית לערך של פרמטר השאילתה addy בבקשה הנכנסת.
    • מגדיר את פועל ה-HTTP לערך GET.
  • הערך של <IgnoreUnresolvedVariables> מוגדר כ-false. כשהערך של <IgnoreUnresolvedVariables> הוא false, אם אחד מהמשתנים שהמדיניות מנסה להוסיף לא קיים, Edge יפסיק את העיבוד בזרימת ה-API.

דוגמה 2

דוגמה נוספת שמראה איך ליצור אובייקט בקשה מותאם אישית באמצעות AssignMessage:

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

בדוגמה הזו נוצרת בקשה חדשה בהתאמה אישית בשם partner.request. לאחר מכן, המערכת מגדירה את הערכים <Verb> ו-<Payload> בבקשה החדשה.

אפשר לגשת להודעת בקשה בהתאמה אישית במדיניות אחרת של AssignMessage שמופיעה בהמשך התהליך. בדוגמה הבאה מקבלים את הערך של הכותרת user-agent של הודעת הבקשה המותאמת אישית:

<AssignMessage name="custom-request-1-access">
  <DisplayName>custom-request-1-access</DisplayName>
  <AssignTo createNew="false" type="request"></AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

סרטונים

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

וידאו תיאור
למה צריך להקצות מדיניות הודעות? כאן אפשר לקרוא על היתרונות של שימוש במדיניות AssignMessage כדי לשנות את הבקשה או התגובה של ה-API בלי לשנות את קוד ה-Backend.
העתקת רכיבי API באמצעות מדיניות AssignMessage העתקת רכיבים מבקשה או מתשובה של API ויצירת אובייקט בקשה או תשובה חדש באמצעות מדיניות AssignMessage.
הסרת רכיבי API באמצעות מדיניות AssignMessage מסירים רכיבי API ומשנים את ה-API לפני שהוא מגיע לשרת העורפי של היעד באמצעות מדיניות AssignMessage.
הוספה והגדרה של רכיבי API באמצעות מדיניות AssignMessage שינוי בקשת API או תגובה על ידי הוספה של פרמטרים של שאילתות, כותרות, פרמטרים של טפסים או מטענים ייעודיים (payloads) באמצעות מדיניות AssignMessage.
יצירת משתנים מותאמים אישית באמצעות מדיניות AssignMessage הגדרת משתני תהליך עבודה מותאמים אישית באמצעות מדיניות AssignMessage ושימוש במשתנים במדיניות אחרת ב-API proxy.
יצירת אובייקטים חדשים של בקשות או תגובות באמצעות מדיניות AssignMessage יוצרים אובייקטים חדשים של בקשות או תגובות ל-API באמצעות מדיניות AssignMessage בזמן הריצה של ה-API.
יצירת API מדומה באמצעות מדיניות AssignMessage כדי ליצור API פשוט ל-REST לצורך הדמיה, מוסיפים את מדיניות AssignMessage לזרימת התגובה.
הגדרה או שינוי של מטען ייעודי (payload) באמצעות מדיניות AssignMessage המרת בקשת REST לבקשת SOAP על ידי הגדרת SOAP Payload באמצעות מדיניות AssignMessage בזמן הריצה של ה-API.

קודי שגיאה

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

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

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

קוד תקלה סטטוס HTTP סיבה תיקון
steps.assignmessage.SetVariableFailed 500 המדיניות לא הצליחה להגדיר משתנה. לראות את מחרוזת השגיאה של שם ה- משתנה שלא נפתר.
steps.assignmessage.VariableOfNonMsgType 500

השגיאה הזו מתקבלת אם המאפיין source ברכיב <Copy> מוגדר כמשתנה שאינו מסוג message.

משתנים של סוגי הודעות מייצגים את כל הבקשות והתשובות של HTTP. אפליקציית Edge המובנית משתני הזרימה request, response ו-message הם מסוג הודעה. מידע נוסף על משתני הודעות קראו את חומר העזר בנושא משתנים.
steps.assignmessage.UnresolvedVariable 500

השגיאה הזו מתקבלת אם המשתנה שצוין במדיניות 'הקצאת הודעה' הוא:

  • לא בהיקף (לא זמין בתהליך הספציפי שבו המדיניות מופעלת)
    • או
  • לא ניתן לפתרון (לא מוגדר)

שגיאות פריסה

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

שם השגיאה סיבה תיקון
InvalidIndex אם האינדקס שצוין ברכיבים <Copy> ו/או <Remove> של הקצאת ההודעה היא 0 או מספר שלילי, אז הפריסה של שרת ה-proxy ל-API נכשלת.
InvalidVariableName אם רכיב הצאצא <Name> ריק או לא צוין ברכיב <AssignVariable>, הפריסה של שרת ה-proxy ל-API נכשלת כי אין שם משתנה חוקי שצריך להקצות לו ערך. צריך להזין שם משתנה חוקי.
InvalidPayload מטען ייעודי (payload) שצוין במדיניות אינו חוקי.

משתני כשל

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

משתנים איפה דוגמה
fault.name="fault_name" fault_name הוא שם השגיאה, כפי שמצוין בטבלה שגיאות זמן ריצה שלמעלה. שם השגיאה הוא החלק האחרון בקוד השגיאה. fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. assignmessage.AM-SetResponse.failed = true

דוגמה לתגובת שגיאה

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

דוגמה לכלל שגוי

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Assign Message Faults">
    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>

סכימות

כל סוג מדיניות מוגדר על ידי סכימת XML ‏ (.xsd). סכימות מדיניות זמינות ב-GitHub.

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

דוגמאות עבודה של מדיניות AssignMessage זמינות בדוגמאות של API Platform.

דוגמה מתקדמת יותר להחלפת target.url מ-ProxyEndpoint מופיעה במאמר הזה בקהילת Apigee.

כדי לראות איך פועלת מדיניות ServiceCallout עם הגדרת נתיב, אפשר לעיין בדוגמה הזו לתרגול מעשי בדוגמאות של Apigee ב-GitHub. פשוט משכפלים את המאגר ופועלים לפי ההוראות בנושא הזה. בדוגמה נעשה שימוש במדיניות AssignMessage כדי להגדיר נתיב בקשה, ואז נעשה שימוש במדיניות Service Callout כדי לשלוח את הבקשה לשירות חיצוני.