‫AssignMessage policy

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

מה

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

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

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

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

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

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

כדי להטמיע משתני זרימה של Edge במטען ייעודי (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>

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

‫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: קבלת כותרות תגובה של Service Callout

בדוגמה הבאה, נניח שמדיניות ServiceCallout נמצאת בבקשת ה-proxy ל-API, והתגובה ל-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 example ב-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> משמש כדי לקבל את הערכים של שלושה פרמטרים של מחרוזת שאילתה מהבקשה הראשונית, ולהגדיר אותם כפרמטרים של טופס בבקשה של נקודת הקצה (endpoint) המטורגטת:

<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 לבקשה שתישלח לנקודת הקצה (endpoint) המטורגטת:

<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> ב-preflow של הבקשה. אם תבדקו את התוצאות בכלי כמו Trace tool, הבקשה ל-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 תשלח את הבקשה ששונתה לנקודת הקצה (endpoint) המטורגטת.

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

username=nick&zip_code=90210&default_language=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> משתמש בתחביר הבא:

תחביר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 שהתקבל על ידי ה-proxy ל-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:

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

דוגמה 3s24

תרחיש נפוץ לשימוש ב-<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

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

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

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

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

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

משתמשים במאפיין 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, מוסיפים את -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, המדיניות הזו מעתיקה את הנתיב מהודעת הבקשה שצוינה במאפיין 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>

דוגמה 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>)

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

אם הערך הוא true, המדיניות הזו מעתיקה את המטען הייעודי (payload) מההודעה שצוינה במאפיין source של הרכיב <Copy> להודעה שצוינה ברכיב <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 מהתגובה שצוינה על ידי המאפיין source של הרכיב <Copy> לתגובה שצוינה על ידי הרכיב <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> רק כשהודעות המקור והיעד הן מסוג Response.

‫<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> רק כשהודעות המקור והיעד הן מסוג Response.

שימוש נפוץ ב-<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>

משתמשים בו בנוסף למאפיין 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> משתמש בתחביר הבא:

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

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

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

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

משתני כשל

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

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

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

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

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

    <FaultRule name="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.

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

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