מדיניות AssignMessage

מוצג התיעוד של Apigee Edge.
נכנסים למסמכי התיעוד של Apigee X.
מידע

מה

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

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

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

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

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

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

בדוגמה הבאה מוטמע הערך של משתנה הזרימה user-agent בכותרת HTTP ברכיב 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. שליחת בקשה לשרת ה-proxy של ה-API. לדוגמה:
    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, והתגובה לתוסף היתרונות המרכזיים מכילה כמה כותרות של אותו שם (Set-Cookie). בהנחה שמשתנה התגובה של תוסף היתרונות המרכזיים של השירות מוגדר כברירת המחדל 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}

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

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

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

כדי להגדיר ערך ברירת מחדל למשתנה של תהליך היעד, משתמשים ב-<Value> בשילוב עם <Ref>. אם משתנה הזרימה שצוין על ידי <Ref> לא קיים, לא ניתן לקריאה או שהוא ריק, 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>. לכן אפשר לשלוח בקשה לשרת ה-proxy של ה-API הזה, ללא פרמטר השאילתה "w":

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

...ושרת ה-API של ה-API עדיין יחזיר תוצאה חוקית.

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

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

<Template> (צאצא של <AssignVariable>)

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

אפשר להשתמש במאפיין 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>)

הערך של המשתנה מסוג 'נתיב של יעד שהושלם' מוגדר באמצעות <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, מוסיפים את הערך -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>)

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

אם הערך הוא 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 אפשר לציין את התו המפריד הראשון במשתנה זרימה. ברירת המחדל היא '{'. אפשר לקרוא מידע נוסף במאמר הסבר על משתני זרימה. אופציונלי צ'אר
variableSuffix אפשר לציין את התו המפריד האחרון במשתנה זרימה. ברירת המחדל היא '}'. מידע נוסף זמין במאמר הסבר על משתני זרימה. אופציונלי צ'אר

<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, שיכולה להעביר את הבקשה המותאמת אישית לשירות חיצוני.

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

דוגמה 1

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

<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 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 בלי לשנות את הקוד של הקצה העורפי.
העתקת רכיבי API באמצעות מדיניות assignMessage אפשר להעתיק רכיבים מבקשה או מתגובה של API ולבנות בקשה או אובייקט תגובה חדשים באמצעות המדיניות assignMessage.
הסרה של רכיבי API באמצעות המדיניות assignMessage מסירים רכיבי API ומשנים את ה-API לפני שהוא מגיע לקצה העורפי של היעד באמצעות המדיניות assignMessage.
הוספה והגדרה של רכיבי API באמצעות המדיניות assignMessage ניתן לשנות את הבקשה או התגובה ל-API על ידי הוספת פרמטרים של שאילתה, כותרות, פרמטרים של טפסים או מטענים ייעודיים (payloads) באמצעות המדיניות assignMessage.
יצירת משתנים מותאמים אישית באמצעות מדיניות assignMessage אפשר להגדיר משתני זרימה מותאמים אישית באמצעות המדיניות assignMessage, ולהשתמש במשתנים בכללי מדיניות אחרים בשרת ה-proxy ל-API.
יצירת אובייקטים חדשים של בקשות או תגובות באמצעות המדיניות assignMessage יצירת אובייקטים חדשים של בקשות או תגובות ל-API באמצעות המדיניות assignMessage בזמן הריצה של ה-API.
יצירת API מדומה באמצעות מדיניות assignMessage כדי ליצור API ל-REST לדוגמה פשוט, מוסיפים את המדיניות assignMessage בתהליך התגובה.
הגדרה או שינוי של המטען הייעודי (payload) באמצעות המדיניות assignMessage כדי להמיר בקשת REST לבקשת SOAP, צריך להגדיר את המטען הייעודי (payload) של SOAP באמצעות המדיניות 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 או מספר שלילי, הפריסה של שרת ה-API של שרת ה-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.

לדוגמה מתקדמת יותר של האופן שבו משנים את target.url מ-ProxyEndpoint, אפשר לעיין במאמר הזה בקהילת Apigee.

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