מדיניות AssignMessage

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

מה

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

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

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

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

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

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

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

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

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

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

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

דוגמאות

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

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

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

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

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

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

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

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

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

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

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>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="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

  1. יוצר שלושה משתני זרימה בבקשה, עם ערכים סטטיים
  2. קבלת משתני התהליך באופן דינמי במדיניות השנייה בתהליך הבקשה
  3. הגדרתם במטען הייעודי (payload) של התגובה
<!-- Policy #1: Set variables in the request -->

<AssignMessage name="AM-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>
</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, ותגובת ה-callout מכילה כמה כותרות עם אותו שם (Set-Cookie). בהנחה שמשתנה התגובה של Service Callout הוא ברירת המחדל calloutResponse, המדיניות הבאה מקבלת את ערך הכותרת השנייה Set-Cookie.

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

{calloutResponse.header.Set-Cookie.values}

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

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

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

<Add>

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

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

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

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

תחבירs1 

<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>

דוגמה 1s2

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

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s3

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

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 3s4

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

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

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

תחבירs5 

<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>

דוגמה 1s6

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

<AssignMessage name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s7

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

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

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

דוגמה 3s8

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

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

username=nick&zip_code=90210&default_language=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> הוא:

תחבירs9 

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

דוגמה 1s10

בדוגמה הבאה מוסיפים כותרת partner-id להודעת הבקשה, ומקצים לכותרת הזו את הערך של משתנה הזרימה verifyapikey.VAK-1.developer.app.partner-id.

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

תחבירs11 

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

דוגמה 1s12

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

<AssignTo>

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

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

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

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

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

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

תחבירs13 

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

דוגמה 1s14

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

<AssignMessage name="assignto-1">
<!-- DO NOT do this -->
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

דוגמה 2s15

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

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

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

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

דוגמה 3s16

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<AssignVariable>

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

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

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

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

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

תחבירs17 

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

דוגמה 1s18

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

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

דוגמה 2s19

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

דוגמה 3s20

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

<AssignMessage name='AV-via-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> הוא:

תחבירs21 

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

דוגמה 1s22

בדוגמה הבאה, משתנה היעד הוא 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>

דוגמה 1s23

בדוגמה הבאה מוקצה הערך של משתנה הזרימה 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 ברירת מחדל (או ערך חלופי) לאף אחת מהמטלות.

דוגמה 2s23

בדוגמה הבאה מוקצה הערך של משתנה הזרימה 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משתנה ה-flow או של פרמטר השאילתה Country הם null, לא ניתנים לקריאה או פגומים, Edge מקצה את הערך ErrorOnCopy למשתנים החדשים.

דוגמה 3s24

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

…ועדיין להחזיר תוצאה תקינה מ-API Proxy.

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

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

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

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

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

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

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

תחבירs25 

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

דוגמה 1s26

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

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

דוגמה 2s27

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

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

דוגמה 3s28

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

<AssignMessage name='AV-template-with-fallback'> 
 <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> הוא:

תחבירs29 

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

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

תחבירs30 

<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>

דוגמה 1s31

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

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

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

דוגמה 2s32

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

<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

לרכיב <Copy> יש מאפיין אחד:

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

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

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

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

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

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

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

תחבירs33 

<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>

דוגמה 1s34

בדוגמה הבאה מועתק פרמטר טופס יחיד מהבקשה לבקשה המותאמת אישית 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>

דוגמה 2s35

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

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

דוגמה 3s36

בדוגמה הבאה מועתקים שלושה פרמטרים של טופס לבקשה המותאמת אישית 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>

דוגמה 4s37

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

<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> הוא:

תחבירs38 

<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>

דוגמה 1s39

בדוגמה הבאה מועתקת הכותרת 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>

דוגמה 2s40

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

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

דוגמה 3s41

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

<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, המדיניות הזו מעתיקה את הנתיב from מהודעת הבקשה שצוינה על ידי המאפיין source של הרכיב <Copy> to להודעת הבקשה שצוינה על ידי הרכיב <AssignTo>.

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

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

תחביר

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

דוגמה 1s42

בדוגמה הבאה מצוין שמדיניות 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, המדיניות מעתיקה את מטען הייעודי מהההודעה שצוינה ברכיב <Copy> באמצעות המאפיין source אל ההודעה שצוינה ברכיב <AssignTo>.

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

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

תחבירs43 

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

דוגמה 1s44

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

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

תחבירs45 

<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>

דוגמה 1s46

בדוגמה הבאה, פרמטר השאילתה 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>

דוגמה 2s47

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

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

דוגמה 3s48

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

<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 from התגובה שצוינה על ידי המאפיין source של הרכיב <Copy> to התגובה שצוינה על ידי הרכיב <AssignTo>.

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

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

תחבירs49 

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

דוגמה 1s50

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

<AssignMessage name="AM-copy-reasonphrase-1">
  <Copy source="serviceCalloutResponse">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

אפשר להשתמש ב-<ReasonPhrase> רק אם הודעות המקור והיעד הן מסוג תגובה.

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

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

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

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

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

תחבירs52 

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

דוגמה 1s53

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

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

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

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

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

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

תחבירs54 

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

דוגמה 1s55

בדוגמה הבאה, הערך של <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> הוא:

תחבירs56 

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

דוגמה 1s57

בדוגמה הבאה, הערך של <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>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<IgnoreUnresolvedVariables>

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

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

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

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

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

תחבירs58 

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

דוגמה 1s59

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

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
</AssignMessage>

מכיוון שהערך של <IgnoreUnresolvedVariables> מוגדר כ-true, אם המשתנה possibly-defined-variable לא מוגדר, המדיניות הזו לא תגרום לשגיאה.

<Remove>

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

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

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

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

תחבירs60 

<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>

דוגמה 1s61

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

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

דוגמה 2s62

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

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 3s63

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

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

בדרך כלל עושים את זה רק אם מתכוונים להשתמש ברכיב <Set> או ברכיב <Copy> כדי להגדיר ערכים חלופיים בהודעה.

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

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

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

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

תחבירs64 

<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>

דוגמה 1s65

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

<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s66

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

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 3s67

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

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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>

דוגמה 1s68

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

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s69

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

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 3s70

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

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</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>

דוגמה 1s71

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

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

תחבירs72 

<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>

דוגמה 1s73

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

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s74

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

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 3s75

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

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

דוגמה 4s76

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

<Set>

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

דוגמה 1s77

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

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s78

בדוגמה הבאה מתבצעת החלפה של המטען הייעודי (payload) של התגובה, וגם של הכותרת Content-Type.

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

תחבירs79 

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

דוגמה 1s80

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

<AssignMessage name="AM-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> הוא:

תחבירs81 

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

דוגמה 1s81

בדוגמה הבאה, הכותרת x-ratelimit-remaining מוגדרת לערך של המשתנה ratelimit.Quota-1.available.count:

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

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

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

תחבירs82 

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

דוגמה 1s83

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

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

דוגמה 2s84

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

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

דוגמה 3s85

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

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

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

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

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

דוגמה 4s86

התוכן של <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> הוא:

תחבירs87 

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

דוגמה 1s88

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

<AssignMessage name="AM-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> הוא:

תחבירs89 

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

דוגמה 1s90

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

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

דוגמה 2s91

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

<AssignMessage name="AM-set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

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

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

תחבירs92 

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

דוגמה 1

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

<AssignMessage name="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

דוגמה 2

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

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</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>

דוגמה 1s93

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

<AssignMessage name="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

דוגמה 2s94

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

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

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

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

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

תחבירs95 

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

דוגמה 1s96

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

<AssignMessage name="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

דוגמה 2

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

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

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

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

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

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

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

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

דוגמה 1s97

בדוגמה הבאה נוצר אובייקט בקשה בהתאמה אישית עם 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.

דוגמה 2s98

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

<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>partner.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.

קודי שגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.assignmessage.SetVariableFailed 500 The policy was not able to set a variable. See the fault string for the name of the unresolved variable.
steps.assignmessage.VariableOfNonMsgType 500

This error occurs if the source attribute in the <Copy> element is set to a variable which is not of type message.

Message type variables represent entire HTTP requests and responses. The built-in Edge flow variables request, response, and message are of type message. To learn more about message variables, see the Variables reference.
steps.assignmessage.UnresolvedVariable 500

This error occurs if a variable specified in the Assign Message policy is either:

  • out of scope (not available in the specific flow where the policy is being executed)
    • or
  • can't be resolved (is not defined)

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidIndex If the index specified in the <Copy> and/or <Remove> elements of the Assign Message policy is 0 or a negative number, then deployment of the API Proxy fails.
InvalidVariableName If the child element <Name> is empty or not specified in the <AssignVariable> element, then the deployment of the API proxy fails because there is no valid variable name to which to assign a value. A valid variable name is required.
InvalidPayload A payload specified in the policy is invalid.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. assignmessage.AM-SetResponse.failed = true

Example error response

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

Example fault rule

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