Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫AssignMessage policy

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

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

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

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

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

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

כדי להטמיע את המדיניות הזו, צריך להגדיר פעולות כמו:

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

המדיניות AssignMessage מבצעת פעולות לפי הסדר שבו הן מופיעות בהגדרת המדיניות. לדוגמה, אם צריך להסיר את כל הכותרות ואז להגדיר כותרת ספציפית, צריך לכלול את הרכיב <Remove> לפני הרכיב <Set>.

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

רכיב `<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>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>

  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

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

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      <!-- Use either GoogleAccessToken or GoogleIDToken  -->
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
      </GoogleAccessToken>

    ----- or -----
      <GoogleIDToken>
        <Audience ref='FLOW_VARIABLE_NAME>TARGET_URL</Scope>
      </GoogleAccessToken>
    </Authentication>
    <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>
    <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 לזרימה בממשק המשתמש של Apigee. סביר להניח שלא תרצו לראות את כל רכיבי ההגדרה שמוצגים כאן.

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <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 בממשק המשתמש של Apigee, התבנית מכילה placeholders לכל הפעולות האפשריות. בדרך כלל בוחרים אילו פעולות רוצים לבצע באמצעות המדיניות הזו ומסירים את שאר רכיבי הצאצא. לדוגמה, אם רוצים לבצע פעולת העתקה, משתמשים ברכיב <Copy> ומסירים את <Add>, <Remove> ושאר רכיבי הצאצא מהמדיניות כדי שהיא תהיה קריאה יותר.

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

מאפיין	ברירת מחדל	חובה?	תיאור
`name`	לא רלוונטי	חובה	השם הפנימי של המדיניות. הערך של מאפיין `name` יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול להיות ארוך מ-255 תווים. אפשר להשתמש ברכיב `<DisplayName>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק המשתמש לניהול.
`continueOnError`	FALSE	אופציונלי	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי
`enabled`	TRUE	אופציונלי	מגדירים את הערך `true` כדי לאכוף את המדיניות, או את הערך `false` כדי להשבית את המדיניות. המדיניות לא נאכפת גם אם היא עדיין משויכת לזרימה.
`async`	FALSE	הוצא משימוש	המאפיין הזה הוצא משימוש.

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

רכיב צאצא	חובה?	תיאור
פעולות נפוצות
`<Add>`	אופציונלי	מוסיף מידע לאובייקט של ההודעה שצוין ברכיב `<AssignTo>`. ‫`<Add>` מוסיף כותרות או פרמטרים להודעה שלא קיימים בהודעה המקורית. שימו לב שגם `<Set>` מספק את הפונקציונליות הזו. כדי להחליף כותרות או פרמטרים קיימים, משתמשים ברכיב `<Set>`.
`<Copy>`	אופציונלי	מעתין מידע מה הודעה שצוינה במאפיין `source` לה הודעה שצוינה ברכיב `<AssignTo>`.
`<Remove>`	אופציונלי	מוחק את הרכיבים שצוינו ממשתנה ההודעה שצוין ברכיב `<AssignTo>`.
`<Set>`	אופציונלי	הפונקציה מחליפה ערכים של מאפיינים קיימים בבקשה או בתגובה, שצוינו על ידי הרכיב `<AssignTo>`. ‫`<Set>` מחליף כותרות או פרמטרים שכבר קיימים בהודעה המקורית או מוסיף חדשים אם הם לא קיימים.
רכיבי צאצא אחרים
`<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: הסרת מטען ייעודי

בדוגמה הבאה, המטען הייעודי למטרה מוסר מהתגובה באמצעות הרכיב <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: הגדרת תוכן דינמי

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

כדי להטמיע משתני זרימה במטען ייעודי (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="AM-set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

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

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

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

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

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

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

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

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

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

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

שולחים בקשה ל-proxy ל-API; לדוגמה:
```
curl -vL https://ahamilton-eval-test.apigee.net/myproxy
```
אם רוצים, אפשר להעביר את התוצאות דרך כלי כמו xmllint כדי שה-XML יוצג במבנה מעוצב:
```
curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -
```
גוף התגובה אמור להיראות כך:
```
  42
  
    test
    gopher
  
```

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

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

‫8: אחסון והסרה של פרמטרים של טפסים, כותרות ופרמטרים של שאילתות

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

<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove">
  <DisplayName>AM-StoreAndRemove</DisplayName>
  <AssignVariable>
    <Name>var_grant_type</Name>
    <Ref>request.formparam.grant_type</Ref>
  </AssignVariable>
  <Remove>
    <Headers/>
    <FormParams/>
    <Payload/>
  </Remove>
  <Set>
    <Headers>
      <Header name="Content-Type">application/x-www-form-urlencoded</Header>
      <Header name="Accept">application/json</Header>
      <Header name="Grant-Type">{var_grant_type}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

הערה: אי אפשר לגשת לפרמטרים של טפסים, לכותרות ולפרמטרים של שאילתות שמוסרים באמצעות <Remove> במדיניות Assign Message אחרי השלמת זרימת המדיניות, אלא אם הערכים שלהם מאוחסנים במשתנים כפי שמתואר בדוגמה הזו.

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

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

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

`<Add>`

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

דוגמה 3

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

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

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

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
  </Add>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

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

דוגמה 3

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

<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
סוג ההודעה: בקשה
אחת (או שתי) מהאפשרויות הבאות:
- נתוני טופס: צריך להגדיר ערך כלשהו או "" (המחרוזת הריקה). לדוגמה, עם<0x000A> 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>, ‏ Apigee מגדיר את הכותרת Content-Type של הבקשה לערך application/x-www-form-urlencoded לפני שליחת ההודעה לשירות היעד.

`<Headers>` (ילד/ה של `<Add>`)

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוסיפים כותרת 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> משתמש בתחביר הבא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

דוגמה 1

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

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

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

פעלים של HTTP: ‏ GET, POST, PATCH, DELETE
סוג ההודעה: בקשה

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

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

`<AssignTo>`

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

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

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

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

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

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

תחביר

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

דוגמה 1

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

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

אם מציינים createNew="false" ולא מספקים שם הודעה באופן מפורש, שאר המאפיינים של <AssignTo> לא רלוונטיים. במקרה כזה, כדאי להשמיט לגמרי את הרכיב <AssignTo>.

דוגמה 2

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

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

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

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

דוגמה 3

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

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

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

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

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

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

מאפיין	תיאור	חובה?	סוג
`createNew`	קובעת אם המדיניות הזו יוצרת הודעה חדשה כשמגדירים ערכים. אם הערך הוא `true`, המדיניות יוצרת משתנה חדש מהסוג שצוין על ידי `type` (`request` או `response`). אם לא מציינים את השם של המשתנה החדש, המדיניות יוצרת אובייקט חדש של בקשה או תגובה, בהתאם לערך של `type`. זהירות: כשיוצרים אובייקט בקשה או תגובה חדש, אובייקט הבקשה או התגובה הקיים נמחק ומוחלף בחדש, כלומר כל המידע באובייקט אובד. אם `false`, המדיניות מגיבה באחת משתי דרכים: אם `<AssignTo>` יכול לפתור את שם המשתנה לבקשה או לתגובה, הוא ממשיך בעיבוד. לדוגמה, אם המדיניות נמצאת בתהליך של בקשה, המשתנה הוא אובייקט הבקשה. אם המדיניות נמצאת בתגובה, המשתנה הוא אובייקט התגובה. אם לא ניתן לפתור את `<AssignTo>`, או אם הוא נפתר לסוג שאינו הודעה, המדיניות מחזירה שגיאה. אם לא מציינים את `createNew`, המדיניות מגיבה באחת משתי דרכים: אם `<AssignTo>` נפתר להודעה, העיבוד עובר לשלב הבא. אם לא ניתן לפתור את `<AssignTo>`, או אם הפתרון הוא לא מסוג הודעה, נוצר משתנה חדש מהסוג שצוין ב-`type`.	אופציונלי	בוליאני
`transport`	מציין את סוג התעבורה של סוג ההודעה של הבקשה או התגובה. ערך ברירת המחדל הוא `http` (הערך הנתמך היחיד).	אופציונלי	String
`type`	מציין את סוג ההודעה החדשה, אם הערך של `createNew` הוא `true`. הערכים התקינים הם `request` או `response`. ערך ברירת המחדל הוא `request`. אם משמיטים את המאפיין הזה, Apigee יוצר בקשה או תגובה, בהתאם למיקום שבו המדיניות הזו מופעלת בתהליך.	אופציונלי	String

createNew

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

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

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

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

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

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

אופציונלי

בוליאני

transport

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

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

אופציונלי

String

type

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

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

אופציונלי

String

`<AssignVariable>`

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

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

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

מחרוזת ליטרלית: משתמשים ברכיב המשני <Value> כדי לציין ערך מחרוזת ליטרלי למשתנה של יעד הזרימה.
משתנה של זרימת נתונים: משתמשים ברכיב הצאצא <Ref> כדי לציין את הערך של משתנה קיים של זרימת נתונים עבור משתנה היעד של זרימת הנתונים. רשימה מלאה של משתנים של זרימת נתונים שאפשר להשתמש בהם כמקור זמינה במאמר הפניה למשתנים של זרימת נתונים.
קבוצת מאפיינים: משתמשים ברכיב הצאצא <PropertySetRef> כדי לאחזר את הערך מצמד שם/מפתח של קבוצת מאפיינים ולאחסן אותו במשתנה של זרימת נתונים. כך אפשר לגשת לקבוצות מאפיינים באופן דינמי.
כתובת URL של משאב: משתמשים ברכיב המשני <ResourceURL> כדי לציין כתובת URL של משאב טקסט, מסוג XSL,‏ XSD,‏ WSDL,‏ JavaScript או OpenAPI Spec. הפעולה הזו מקצה את התוכן של המשאב למשתנה של זרימת נתונים עם שם.
תבנית הודעה: משתמשים ברכיב המשני <Template> כדי לציין תבנית הודעה למשתנה של זרימת היעד.

סדר העדיפות של אלמנטי הצאצא האלה הוא: ResourceURL, ‏ Template, ‏ Ref, ‏ Value,‏ PropertySetRef.

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

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

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

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

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

דוגמה 3

בדוגמה הבאה נעשה שימוש ברכיב הצאצא <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>

דוגמה 4

בדוגמה הבאה נעשה שימוש ב-<AssignVariable> כדי להשבית את התנהגות ברירת המחדל של העברת סיומת הנתיב מבקשת ה-proxy לבקשת היעד:

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

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

`<Name>` (ילד/ה של `<AssignVariable>`)

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

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

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

תחביר

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

דוגמה 1

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

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

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

הערה: השם ratelimit שמור. מידע נוסף זמין בQuota Policy Throws NullPointerException בקהילת Apigee.

`<PropertySetRef>` (ילד/ה של `<AssignVariable>`)

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

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

קבוצת מאפיינים מורכבת מצמד של שם/מפתח. לדוגמה: propset1.id=12345, כאשר propset1 הוא השם של קבוצת המאפיינים, id הוא מפתח ו-12345 הוא הערך של המפתח.

רכיב הבן PropertySetRef מאפשר לבחור באופן דינמי שמות של קבוצות מאפיינים או מפתחות. נניח שיש לכם 200 כללי ניתוב בקובץ של קבוצת נכסים. אפשר לגשת לכללים של קבוצת המאפיינים באופן הבא, כאשר routingrules הוא השם של קבוצת המאפיינים ו-rule1,‏ rule2 ו-rulen הם מפתחות:

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

כדי לגשת למאפיינים האלה בתהליך של שרת proxy ל-API, צריך לדעת איזה כלל רוצים לבחור בזמן העיצוב. עם זאת, נניח ששם הכלל מופיע בכותרת הבקשה או במטען הייעודי (payload). אחת הדרכים לבחור את הכלל היא להשתמש במדיניות JavaScript עם קוד כמו זה שמופיע בהמשך:

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

לעומת זאת, התכונה AssignMessage PropertySetRef מאפשרת לבחור מפתח מאפיין באופן דינמי בלי להשתמש ב-JavaScript.

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

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

רכיב <PropertySetRef> משתמש בתחביר הבא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

דוגמה 1

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

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef>
  </AssignVariable>
</AssignMessage>

אפשר להשתמש בכל שילוב של משתני זרימה ומחרוזות מילוליות ברכיב <PropertySetRef>.

דוגמה 2

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

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef>
  </AssignVariable>
</AssignMessage>

אפשר להשתמש בכל שילוב של משתני זרימה ומחרוזות מילוליות ברכיב <PropertySetRef>.

`<Ref>` (ילד/ה של `<AssignVariable>`)

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

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

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

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

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Ref>SOURCE_VARIABLE</Ref>
  </AssignVariable>
</AssignMessage>

דוגמה 1

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

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

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

דוגמה 2

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

דוגמה 3

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

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

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

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

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

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

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

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

אם מציינים משתנה של זרימה שלא קיים עבור הערך של <Ref>, והערך של <IgnoreUnresolvedVariables> הוא false, מערכת Apigee תציג שגיאה.

`<ResourceURL>` (ילד/ה של `<AssignVariable>`)

מציין את כתובת ה-URL של משאב טקסט כמקור להקצאת המשתנה. ‫Apigee טוען את משתנה ה-flow שצוין ב-<Name> עם התוכן של המשאב שאליו יש הפניה. המקור יכול להיות מסוג XSD,‏ XSL,‏ WSDL,‏ JavaScript,‏ Property Set או OpenAPI Spec.

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

אם המשאב שצוין על ידי <ResourceURL> לא קיים, אז: אם הערך של <IgnoreUnresolvedVariables> הוא true,‏ Apigee מקצה את הערך null למשתנה של יעד ה-Flow. אם הערך של <IgnoreUnresolvedVariables> הוא false,‏ Apigee מחזירה שגיאה.

רכיב <ResourceURL> משתמש בתחביר הבא:

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>

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

jsc://my-js-file.js
wsdl://{variable-goes-here}
{variable-goes-here}

דוגמה 1

בדוגמה הבאה, הערך של משאב JSON, שנטען לשרת ה-proxy בתיקייה jsc, מוקצה למשתנה של זרימת העבודה assigned-variable:

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

דוגמה 2

בדוגמה הבאה מוקצה הערך של משאב OpenAPI Spec, שנטען לשרת ה-proxy בתיקייה oas, למשתנה של התהליך assigned-variable, ואז הערך הזה מוגדר כ-Payload בגוף התגובה:

<AssignMessage name='AM-Response'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>oas://Fulfillment.yaml</ResourceURL>
  </AssignVariable>
  <Set>
    <Payload contentType='application/yaml'>{assigned-variable}</Payload>
  </Set>
</AssignMessage>

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

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
  </AssignVariable>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

<AssignMessage name='AV-template-with-fallback'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

`<Value>` (ילד/ה של `<AssignVariable>`)

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

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

`<Copy>`

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
    <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</AssignMessage>

דוגמה 1

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

דוגמה 2

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

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

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

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

מקור

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

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

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

אופציונלי

String

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

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

דוגמה 4

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

<AssignMessage name="AM-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 יש רק ערך אחד, הוא לא מועתק.

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

סוג ההודעה במקור וביעד הוא בקשה
פועל ה-HTTP גם למקור וגם ליעד הוא POST או PUT
ההודעה המקורית כוללת את הכותרת Content-Type עם הערך application/x-www-form-urlencoded.

כשמעתיקים את <FormParams>, הכותרת Content-Type מוגדרת ב-<Copy> בהודעת היעד (שמצוינת על ידי האלמנט <AssignTo>) ל-application/x-www-form-urlencoded.

`<Headers>` (ילד/ה של `<Copy>`)

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

<AssignMessage name="AM-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="VARIABLE_NAME">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

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

סוג ההודעה במקור וביעד הוא בקשה

`<Payload>` (ילד/ה של `<Copy>`)

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

דוגמה 1

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

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

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

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

פעלים של HTTP: ‏ GET, PUT, POST, PATCH, DELETE
סוג ההודעה במקור וביעד הוא בקשה

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

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

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

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

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

סוג ההודעה במקור וביעד הוא בקשה

`<Version>` (ילד/ה של `<Copy>`)

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

דוגמה 1

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

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

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

סוג ההודעה במקור וביעד הוא בקשה

`<DisplayName>`

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

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

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

רכיב <DisplayName> משתמש בתחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

דוגמה

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

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

`<IgnoreUnresolvedVariables>`

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

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

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

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

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

תחביר

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

דוגמה 1

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

מסיר כותרות, פרמטרים של שאילתות, פרמטרים של טפסים ו/או את מטען התשלום של ההודעה מההודעה. תג <Remove> ריק מסיר הכול מההודעה.

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

דוגמה 1

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

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

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

דוגמה 2

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

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

דוגמה 3

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

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

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

<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" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

<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" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

דוגמה 1

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

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

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

<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 יש רק ערך אחד, הוא לא יוסר.

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

פעלים של HTTP: ‏ GET, POST, PATCH, DELETE
סוג ההודעה: בקשה

`<Set>`

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

כותרות ופרמטרים של שאילתות, טפסים והודעות HTTP עשויים להכיל כמה ערכים. כדי להוסיף ערכים נוספים לכותרת או לפרמטר, צריך להשתמש ברכיב <Add>.

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      <!-- Use either GoogleAccessToken or GoogleIDToken  -->
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
      </GoogleAccessToken>

    ----- or -----
      <GoogleIDToken>
        <Audience ref='FLOW_VARIABLE_NAME>TARGET_URL</Scope>
      </GoogleAccessToken>
    </Authentication>
    <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>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

‫<Authentication> (צאצא של `<Set>`)

יוצר אסימון גישה מסוג Google OAuth 2.0 או אסימון מזהה מסוג OpenID Connect שהונפק על ידי Google, ומגדיר אותו בכותרת Authorization. האפשרות הזו שימושית כששרת ה-proxy צריך לבצע קריאות מאומתות לשירותי Google ולשירותים בהתאמה אישית שפועלים במוצרים מסוימים של Google Cloud, כמו Cloud Functions ו-Cloud Run. כדי להשתמש ברכיב הזה, צריך לבצע את שלבי ההגדרה והפריסה שמתוארים במאמר בנושא שימוש באימות של Google. עם הגדרה נכונה, המדיניות יוצרת בשבילכם טוקן ומוסיפה אותו לכותרת המתאימה בבקשה.

רכיבי הצאצא, GoogleAccessToken ו-GoogleIDToken, מאפשרים להגדיר את המדיניות כך שייווצר אסימון Google OAuth או OpenID Connect. אתם בוחרים אחד מהרכיבים הצאצאים האלה בהתאם לדרישה של השירות שאליו אתם רוצים להתקשר.

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

רכיב Authentication משתמש בתחביר הבא:

תחביר

<AssignMessage>
  ...
  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      --EITHER--
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
            ...
        </Scopes>
      <GoogleAccessToken>

      --OR--
      <GoogleIDToken>
        <Audience ref="FLOW_VARIABLE">TARGET_URL</Audience>
      </GoogleIDToken>

    </Authentication>
  </Set>
  ...
</AssignMessage>

שימוש בטוקן גישה

בדוגמה הבאה מוצג הרכיב GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

שימוש באסימון מזהה

בדוגמה הבאה מוצג הרכיב GoogleIDToken:

<Authentication>
  <GoogleIDToken>
    <Audience>https://httpserver0-bar.run.app</Audience>
  </GoogleIDToken>
</Authentication>

שימוש ב-HeaderName

בדוגמה הבאה מוצג הרכיב HeaderName:

  <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scopes>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

‫<HeaderName> (צאצא של `<Authentication>`)

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

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

רכיב HeaderName משתמש בתחביר הבא:

תחביר

<AssignMessage>
...
  <Authentication>
    <HeaderName>HEADER_NAME</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</AssignMessage>

עם מחרוזת סטטית

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

<Authentication>
  <HeaderName>Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

עם הפניה למשתנה

בדוגמה הזו, אסימון ה-Bearer שנוצר נוסף כברירת מחדל לכותרת בשם Authorization שנשלחת למערכת היעד. אם ל-my-variable יש ערך, המערכת תשתמש בערך הזה במקום במחרוזת ברירת המחדל. הכותרת Authorization, אם היא קיימת, לא משתנה ונשלחת גם היא בבקשה.

<Authentication>
  <HeaderName ref='my-variable'>Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scopes>https://www.googleapis.com/auth/cloud-platform</Scopes>
    </Scopes>
  >/GoogleAccessToken>
</Authentication>

‫<GoogleAccessToken> (צאצא של `<Authentication>`)

יוצר אסימונים של Google OAuth 2.0 כדי לבצע קריאות מאומתות לשירותי Google. אפשר להשתמש באסימוני OAuth של Google כדי לקרוא לשירותים רבים של Google, כמו Cloud Logging ו-Secret Manager.

ערך ברירת המחדל	לא רלוונטי
חובה?	צריך להוסיף את רכיב הבן `GoogleAccessToken` או `GoogleIDToken`.
סוג	String
רכיב אב	`<Authentication>`
רכיבי צאצא	`<Scopes>`

רכיב GoogleAccessToken משתמש בתחביר הבא:

תחביר

<AssignMessage>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
    >/GoogleAccessToken>
  </Authentication>
  ...
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוצג הרכיב GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scopes>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

‫<Scopes> (צאצא של `<GoogleAccessToken>`)

מזהה את היקפי ההרשאות שייכללו באסימון הגישה מסוג OAuth 2.0. למידע נוסף, אפשר לעיין במאמר היקפי הרשאות של OAuth 2.0 ל-Google APIs. אפשר להוסיף רכיב צאצא אחד או יותר <Scope> מתחת לרכיב הזה.

ערך ברירת המחדל	לא רלוונטי
חובה?	חובה
סוג	String
רכיב אב	`<GoogleAccessToken>`
רכיבי צאצא	`<Scope>`

רכיב Scopes משתמש בתחביר הבא:

  <Scopes>
    <Scope>SCOPE_1</Scope>
    <Scope>SCOPE_2</Scope>
    ...
  </Scopes>

‫<Scope> (צאצא של `<Scopes>`)

מציין היקף תקף של Google API. למידע נוסף, אפשר לעיין במאמר בנושא היקפי OAuth 2.0 ל-Google APIs.

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

רכיב Scope משתמש בתחביר הבא:

  <Scope>SCOPE_1</Scope>

‫<GoogleIDToken> (צאצא של `<GoogleAccessToken>`)

יצירת אסימונים של OpenID Connect שהונפקו על ידי Google כדי לבצע קריאות מאומתות לשירותי Google.

ערך ברירת המחדל	לא רלוונטי
חובה?	צריך להוסיף את רכיב הבן `GoogleAccessToken` או `GoogleIDToken`.
סוג	String
רכיב אב	`<Authentication>`
רכיבי צאצא	`<Audience>`

רכיב GoogleIDToken משתמש בתחביר הבא:

תחביר

<AssignMessage>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="FLOW_VARIABLE_NAME">TARGET_URL</Audience>
    </GoogleIDToken>
  </Authentication>
</AssignMessage>

דוגמה 1

בדוגמה הבאה מוצג הרכיב GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
  </GoogleIDToken>
</Authentication>

‫<Audience> (צאצא של `<GoogleAccessToken>`)

הקהל של אסימון האימות שנוצר, למשל ה-API או החשבון שהאסימון מעניק גישה אליהם.

אם הערך של Audience ריק או שהמשתנה ref לא מתפרש כערך תקין, וגם useTargetUrl הוא true, כתובת ה-URL של היעד (לא כולל פרמטרים של שאילתה) משמשת כקהל. ערך ברירת המחדל של useTargetUrl הוא false.

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

רכיב Audience משתמש בתחביר הבא:

  <Audience>TARGET_URL</Audience>

or:

  <Audience ref='FLOW_VARIABLE_NAME'/>

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

דוגמה 1

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

<AssignMessage name="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
סוג ההודעה: בקשה

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

כשמשתמשים ב-<Set> עם <FormParams>, המערכת של Apigee משנה את Content-Type של ההודעה ל-application/x-www-form-urlencoded.

`<Headers>` (ילד/ה של `<Set>`)

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

דוגמה 1

בדוגמה הבאה, הכותרת 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>`)

הערה:

לפעמים צריך לשלוח הודעה לכתובת URL ששונה מכתובת ה-URL שמוגדרת ב-TargetEndpoint של שרת proxy של API. אם רוצים לכתוב מחדש את כתובת ה-URL של היעד, צריך להגדיר מדיניות AssignMessage עם רכיב <AssignVariable>, לצרף אותה ל-TargetEndpoint ולבטל את ההגדרה של המשתנה target.url. (אי אפשר לבטל את target.url במדיניות שמצורפת ל-ProxyEndpoint, כי Apigee מאתחל את המשתנה ב-TargetEndpoint).

בדוגמה הבאה מוצג אופן ההגדרה של מדיניות שתבטל את ההגדרה target.url. אם המדיניות הזו מצורפת לבקשה TargetEndpoint, שרת ה-proxy יפעיל את כתובת ה-URL שבהמשך במקום כתובת ה-URL שהוגדרה בבקשה TargetEndpoint.

<AssignMessage name="AM-Override-Target-URL">
  ...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>https://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
  ...

אפשר גם להשתמש במדיניות JavaScript ב-TargetEndpoint כדי לשנות את target.url.

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

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
  </Set>
</AssignMessage>

דוגמה 1

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

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

דוגמה 2

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

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

דוגמה 3

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

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

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

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

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

דוגמה 4

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

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

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

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

מאפיין	תיאור	נוכחות	סוג
`contentType`	אם מציינים ערך, הוא מוקצה לכותרת ה-HTTP‏ `Content-Type`.`contentType`	אופציונלי	String
`variablePrefix`	אפשר לציין את התו שמשמש כתוחם מוביל במשתנה של זרימת נתונים. ברירת המחדל היא '{". מידע נוסף זמין במאמר הפניה למשתני זרימה.	אופציונלי	Char
`variableSuffix`	אפשר לציין את התו שמגדיר את סוף המשתנה של זרימת נתונים. ברירת המחדל היא '}'. מידע נוסף זמין במאמר הפניה למשתנים של זרימת נתונים.	אופציונלי	Char

`<QueryParams>` (ילד/ה של `<Set>`)

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

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

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

תחביר

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

דוגמה 1

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

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

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

פעלים של HTTP: ‏ GET, PUT, POST, PATCH, DELETE
סוג ההודעה: בקשה

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

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

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

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

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

תחביר

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

דוגמה 1

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

<AssignMessage name="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>

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

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

`<Verb>` (ילד/ה של `<Set>`)

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

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

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

תחביר

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

דוגמה 1

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

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

דוגמה 2

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

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

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

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

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

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

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

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

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

תחביר

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

דוגמה 1

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

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

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

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

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

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

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

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

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

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

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

דוגמה 1

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

<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> לא מציין את המאפיין source, ‏ Apigee ישתמש בהודעה request כמקור שממנו יועתק from.
- מגדיר את פרמטר השאילתה address בהודעה המותאמת אישית לערך של פרמטר השאילתה addy בבקשה הנכנסת.
- מגדיר את פועל ה-HTTP לערך GET.
מגדירים את <IgnoreUnresolvedVariables> לערך false. כש-<IgnoreUnresolvedVariables> הוא false, אם אחד מהמשתנים שמפנים אליהם בהגדרת המדיניות לא קיים, Apigee יעבור למצב שגיאה בתהליך העבודה של ה-API.

דוגמה 2

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

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

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

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

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

קודי שגיאה

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

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

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

קוד תקלה סטטוס HTTP מטרה תיקון

steps.assignmessage.SetVariableFailed 500 המדיניות לא הצליחה להגדיר משתנה. שם המשתנה שלא נפתר מופיע במחרוזת השגיאה.

קוד תקלה	סטטוס HTTP	מטרה
`steps.assignmessage.SetVariableFailed`	`500`	המדיניות לא הצליחה להגדיר משתנה. שם המשתנה שלא נפתר מופיע במחרוזת השגיאה.
`steps.assignmessage.VariableOfNonMsgType`	`500`	השגיאה הזו מתרחשת אם המאפיין `source` ברכיב `<Copy>` מוגדר למשתנה שלא מסוג message. משתני סוג ההודעה מייצגים בקשות ותגובות מלאות של HTTP. המשתנים המובנים של Apigee flow‏ `request`, `response` ו-`message` הם מסוג message. מידע נוסף על משתני הודעות זמין במאמר בנושא משתנים.
`steps.assignmessage.UnresolvedVariable`	`500`	השגיאה הזו מתרחשת אם משתנה שצוין במדיניות AssignMessage הוא אחד מהבאים: לא רלוונטי (לא זמין בתהליך הספציפי שבו המדיניות מופעלת) או אי אפשר לפתור (לא מוגדר)

steps.assignmessage.VariableOfNonMsgType

500

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

משתני סוג ההודעה מייצגים בקשות ותגובות מלאות של HTTP. המשתנים המובנים של Apigee flow‏ request, response ו-message הם מסוג message. מידע נוסף על משתני הודעות זמין במאמר בנושא משתנים.

steps.assignmessage.UnresolvedVariable

500

השגיאה הזו מתרחשת אם משתנה שצוין במדיניות AssignMessage הוא אחד מהבאים:

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

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

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

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

משתני תקלות

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

משתנים	כאשר:	דוגמה
`fault.name="FAULT_NAME"`	‫`FAULT_NAME` הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name Matches "UnresolvedVariable"`
`assignmessage.POLICY_NAME.failed`	‫`POLICY_NAME` הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	`assignmessage.AM-SetResponse.failed = true`

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

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

{  
   "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 Platform.

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

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

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

רכיב <AssignMessage>

תחביר

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

דוגמאות

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

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

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

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

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

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

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

‫8: אחסון והסרה של פרמטרים של טפסים, כותרות ופרמטרים של שאילתות

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

<Add>

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

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

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

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

תחביר

דוגמה 1

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

תחביר

דוגמה 1

<AssignTo>

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

<AssignVariable>

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

דוגמה 4

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

תחביר

דוגמה 1

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

תחביר

דוגמה 1

דוגמה 2

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

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

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

תחביר

דוגמה 1

דוגמה 2

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

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

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

תחביר

דוגמה 1

דוגמה 2

<Copy>

תחביר

דוגמה 1

דוגמה 2

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

תחביר

דוגמה 1

דוגמה 2

דוגמה 3

דוגמה 4

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

תחביר

דוגמה 1

דוגמה 2

‫AssignMessage policy

רכיב `<AssignMessage>`

`<Add>`

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

`<Headers>` (ילד/ה של `<Add>`)

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

`<AssignTo>`

`<AssignVariable>`

`<Name>` (ילד/ה של `<AssignVariable>`)

`<PropertySetRef>` (ילד/ה של `<AssignVariable>`)

`<Ref>` (ילד/ה של `<AssignVariable>`)

`<ResourceURL>` (ילד/ה של `<AssignVariable>`)

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

`<Value>` (ילד/ה של `<AssignVariable>`)

`<Copy>`

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

`<Headers>` (ילד/ה של `<Copy>`)

`<Path>` (ילד/ה של `<Copy>`)

`<Payload>` (ילד/ה של `<Copy>`)

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

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

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

`<Version>` (ילד/ה של `<Copy>`)

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

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

`<Headers>` (ילד/ה של `<Remove>`)

`<Payload>` (ילד/ה של `<Remove>`)

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

`<Set>`

‫<Authentication> (צאצא של `<Set>`)

‫<HeaderName> (צאצא של `<Authentication>`)

‫<GoogleAccessToken> (צאצא של `<Authentication>`)

‫<Scopes> (צאצא של `<GoogleAccessToken>`)

‫<Scope> (צאצא של `<Scopes>`)

‫<GoogleIDToken> (צאצא של `<GoogleAccessToken>`)