خط‌مشی AssignMessage

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید.
اطلاعات

چه

خط‌مشی AssignMessage پیام‌های درخواست و پاسخ جدید را درطول «جریان» میانای برنامه‌سازی کاربردی پراکسی تغییر می‌دهد یا ایجاد می‌کند. این خط‌مشی به شما امکان می‌دهد کنش‌های زیر را روی آن پیام‌ها انجام دهید:

  • افزودن پارامترهای فرم، سرصفحه‌ها، یا پارامترهای پُرسمان جدید به پیام
  • کپی کردن ویژگی‌های موجود از یک پیام به پیام دیگر
  • برداشتن سرصفحه‌ها، پارامترهای پُرسمان، پارامترهای فرم، و/یا محموله‌های پیام از پیام
  • تنظیم مقدار مشخصه‌های موجود در پیام

با خط‌مشی AssignMessage، معمولاً ویژگی‌های درخواست یا پاسخ را اضافه، تغییر، یا حذف می‌کنید. بااین‌حال، می‌توانید از خط‌مشی AssignMessage برای ایجاد پیام درخواست یا پاسخ سفارشی نیز استفاده کنید و آن را به هدف جایگزین ارسال کنید، همان‌طور که در ایجاد پیام‌های درخواست سفارشی توضیح داده شده است.

خط‌مشی AssignMessage می‌تواند پیام‌ها یا متغیرهای جریان را ایجاد یا تغییر دهد. از این خط‌مشی برای اصلاح پیام‌های درخواست قبل‌از ارسال آن‌ها ازطریق پراکسی به سیستم‌های بالادستی، یا برای اصلاح پیام‌های پاسخ قبل‌از رله کردن آن‌ها به برنامه‌های مصرف‌کننده API استفاده کنید.

<AssignMessage> عنصر

خط‌مشی AssignMessage را تعریف می‌کند.

مقدار پیش‌فرض برگه خط‌مشی پیش‌فرض را در زیر ببینید
الزامی است؟ الزامی
تایپ کردن شیء پیچیده
عنصر ولی نامربوط
عناصر فرزند <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

عنصر <AssignMessage> از نحو زیر استفاده می‌کند:

نحو

عنصر <AssignMessage> از نحو زیر استفاده می‌کند:

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

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

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

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

  <DisplayName>policy_display_name</DisplayName>

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

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

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

</AssignMessage>

خط‌مشی پیش‌فرض

مثال زیر تنظیمات پیش‌فرض را هنگام افزودن خط‌مشی AssignMessage به جریان در Edge UI نشان می‌دهد:

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

وقتی خط‌مشی AssignMessage جدیدی را در Edge UI درج می‌کنید، الگو حاوی کدهای ناقص برای همه عملیات‌های ممکن است. معمولاً، عملیات(هایی) را که می‌خواهید با این خط‌مشی انجام دهید انتخاب می‌کنید و بقیه عناصر فرزند را حذف می‌کنید. برای مثال، اگر می‌خواهید عملیات کپی انجام دهید، از عنصر <Copy> استفاده کنید و <Add>، <Remove>، و دیگر عناصر فرزند را از خط‌مشی بردارید تا خواناتر شود.

این عنصر دارای ویژگی های زیر است که در همه سیاست ها مشترک است:

صفت پیش فرض ضروری؟ شرح
name N/A ضروری

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

continueOnError نادرست اختیاری برای بازگرداندن خطا در صورت شکست خط مشی، روی "false" تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است. روی "true" تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.
enabled درست است، واقعی اختیاری برای اجرای این خط‌مشی روی «درست» تنظیم کنید. برای «خاموش کردن» خط مشی، روی «نادرست» تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.
async نادرست منسوخ این ویژگی منسوخ شده است.

جدول زیر شرحی کلی از عناصر فرزند <AssignMessage> ارائه می‌دهد:

عنصر فرزند الزامی است؟ شرح
عملیات رایج
<Add> اختیاری اطلاعات را به شیء پیام که توسط عنصر <AssignTo> مشخص شده است اضافه می‌کند.

<Add> سرایندها یا پارامترهایی به پیام اضافه می‌کند که در پیام اصلی وجود ندارند. برای رونویسی کردن سرصفحه‌ها یا پارامترهای موجود، از عنصر <Set> استفاده کنید.

<Copy> اختیاری اطلاعات را از پیام مشخص‌شده با مشخصه source به شیء پیام مشخص‌شده با عنصر <AssignTo> کپی می‌کند.
<Remove> اختیاری عناصر مشخص‌شده را از متغیر پیام مشخص‌شده در عنصر <AssignTo> حذف می‌کند.
<Set> اختیاری مقادیر ویژگی‌های موجود در درخواست یا پاسخ را جایگزین می‌کند، که توسط عنصر <AssignTo> مشخص می‌شود.

<Set> سرایندها یا پارامترهایی را که ازقبل در پیام اصلی وجود دارند رونویسی می‌کند. برای افزودن سرصفحه یا پارامتر جدید، از عنصر <Add> استفاده کنید.

عناصر فرزند دیگر
<AssignTo> اختیاری مشخص می‌کند که خط‌مشی AssignMessage روی کدام پیام اعمال می‌شود. این پیام می‌تواند درخواست یا پاسخ استاندارد باشد، یا می‌تواند پیام سفارشی جدیدی باشد.
<AssignVariable> اختیاری مقداری را به متغیر جریان اختصاص می‌دهد. اگر متغیر وجود نداشته باشد، <AssignVariable> آن را ایجاد می‌کند.
<IgnoreUnresolvedVariables> اختیاری تعیین می‌کند که آیا پردازش هنگام مواجهه با متغیر حل‌نشده متوقف شود یا نه.

هریک از این عناصر فرزند در بخش‌های زیر شرح داده شده‌اند.

مثال‌ها

نمونه‌های زیر برخی‌از روش‌هایی را نشان می‌دهند که می‌توانید از خط‌مشی AssignMessage استفاده کنید:

۱: افزودن سرایند

مثال زیر با عنصر <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>

‫۲: حذف بار مفید

مثال زیر بار داده را از پاسخ با عنصر <Remove> حذف می‌کند:

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

‫۳: اصلاح کردن پاسخ

مثال زیر شیء پاسخ موجود را با افزودن سرصفحه به آن اصلاح می‌کند:

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

این مثال پیام جدیدی ایجاد نمی‌کند. درعوض، پیام پاسخ موجود را با افزودن سرصفحه HTTP اصلاح می‌کند.

چون این مثال response را به‌عنوان نام متغیر در عنصر <AssignTo> مشخص می‌کند، این خط‌مشی شیء پاسخ را که در ابتدا با داده‌های برگردانده‌شده توسط سرور هدف تنظیم شده بود اصلاح می‌کند.

سرصفحه HTTP که توسط این خط‌مشی به پیام پاسخ اضافه شده است از متغیری مشتق شده است که توسط خط‌مشی LookupCache پر شده است. بنابراین پیام پاسخ اصلاح‌شده توسط این خط‌مشی «اختصاص پیام» حاوی سرصفحه HTTP است که نشان می‌دهد نتایج از حافظه نهان بیرون کشیده شده‌اند یا نه. تنظیم سرصفحه‌ها در پاسخ می‌تواند برای اشکال‌زدایی و عیب‌یابی مفید باشد.

۴: تنظیم محتوای پویا

می‌توانید از Assign Message برای جاسازی محتوای پویا در بار داده پاسخ و پیام‌های درخواست استفاده کنید.

برای جاسازی متغیرهای جریان Edge در پایه‌بار 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>

برای محموله‌های JSON، می‌توانید متغیرها را بااستفاده از مشخصه‌های variablePrefix و variableSuffix با نویسه‌های جداکننده درج کنید، همان‌طور که در مثال زیر نشان داده شده است:

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

برای مشاهده فهرست کامل متغیرهای جریان، به مرجع متغیرهای جریان مراجعه کنید.

از نسخه ابری 16.08.17، می‌توانید از آکولاد هم برای درج متغیرها استفاده کنید.

‫۵: حذف پارامتر پُرسمان

مثال زیر پارامتر پرسمان apikey را از درخواست برمی‌دارد:

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

بهترین روش این است که وقتی از خط‌مشی VerifyAPIKey برای اصالت‌سنجی کاربر استفاده می‌کنید، پارامتر پُرسمان apikey را از پیام درخواست حذف کنید. این کار را برای جلوگیری از ارسال اطلاعات کلیدی حساس به هدف پسین انجام می‌دهید.

‫۶: تنظیم/دریافت متغیرها

مثال زیر از سه خط‌مشی «اختصاص پیام» استفاده می‌کند:

  1. سه متغیر جریان با مقادیر ایستا در درخواست ایجاد می‌کند
  2. متغیرهای جریان را به‌طور پویا در خط‌مشی دوم در جریان درخواست دریافت می‌کند
  3. آن‌ها را در بار داده پاسخ تنظیم می‌کند
<!-- 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. خط‌مشی سوم را در جریان پاسخ اضافه کنید.
  3. خط‌مشی سوم از عنصر <Set> برای افزودن متغیرها به پاسخ استفاده می‌کند. نمونه زیر یک محموله XML در پاسخی که Edge به مشتری برمی‌گرداند می‌سازد:
    <!-- Policy #3: Add variables to the response -->
    <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
      <DisplayName>put-em-in-the-payload</DisplayName>
      <Set>
        <Payload contentType="application/xml">
          <wrapper>
            <secret>{secret}</secret>
            <config>
              <environment>{environment}</environment>
              <protocol>{protocol}</protocol>
            </config>
          </wrapper>
        </Payload>
      </Set>
      <IgnoreUnresolvedVariables>true
      </IgnoreUnresolvedVariables>
      <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>

    توجه داشته باشید که نحو دسترسی به متغیرهای جریان در <Set> این است که آن‌ها را در آکولاد قرار دهید.

    حتماً مشخصه contentType عنصر <Payload> را روی «application/xml» تنظیم کنید.

  4. درخواستی به پراکسی میانای برنامه‌سازی کاربردی خود ارسال کنید؛ برای مثال:
    curl -vL https://ahamilton-eval-test.apigee.net/myproxy

    درصورت تمایل، می‌توانید نتایج را ازطریق ابزاری مانند xmllint لوله‌کشی کنید تا XML در ساختاری با قالب‌بندی زیبا نمایش داده شود:

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

    بدنه پاسخ باید شبیه به موارد زیر باشد:

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

‫۷: دریافت سرصفحه‌های پاسخ «فراخوان سرویس»

در مثال زیر، فرض کنید که خط‌مشی ServiceCallout در درخواست پراکسی میانای برنامه‌سازی کاربردی وجود دارد، و پاسخ فراخوانی حاوی چند سرصفحه با نام یکسان (Set-Cookie) است. با فرض اینکه متغیر پاسخ «فراخوانی سرویس» مقدار پیش‌فرض calloutResponse باشد، خط‌مشی زیر مقدار سرصفحه دوم Set-Cookie را دریافت می‌کند.

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

برای فهرست کردن همه مقادیر سرایند، از متغیر زیر استفاده کنید:

{calloutResponse.header.Set-Cookie.values}

هر عنصر فرزند در این مرجع نمونه‌های بیشتری دارد. برای مثال‌های بیشتر، مثال AssignMessage را در GitHub ببینید.

مرجع عنصر فرزند

این بخش عناصر فرزند <AssignMessage> را شرح می‌دهد.

<Add>

اطلاعاتی را به درخواست یا پاسخ اضافه می‌کند که توسط عنصر <AssignTo> مشخص شده است.

عنصر <Add> ویژگی‌های جدیدی به پیام اضافه می‌کند که در پیام اصلی وجود ندارد. برای تغییر دادن مقادیر ویژگی‌های موجود، از عنصر <Set> استفاده کنید.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن نوع پیچیده
عنصر ولی <AssignMessage>
عناصر فرزند <FormParams>
<Headers>
<QueryParams>

عنصر <Add> از نحو زیر استفاده می‌کند:

نحوs1

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

نمونه ۱s2

مثال زیر از عنصر <FormParams> برای دریافت مقادیر سه پارامتر رشته پُرسمان از درخواست اولیه و تنظیم آن‌ها به‌عنوان پارامترهای فرم در درخواست نقطه پایانی هدف استفاده می‌کند:

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

نمونه ۲s3

مثال زیر از عنصر <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>

مثال ۳s4

مثال زیر از عنصر <QueryParams> برای افزودن یک پارامتر پُرسمان با مقدار ایستا به درخواست استفاده می‌کند:

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

این مثال از <Add> در پیش‌جریان درخواست استفاده می‌کند. اگر نتایج را در ابزاری مثل ابزار ردیابی ببینید، درخواست به https://example-target.com/get به https://example-target.com/get?myParam=42 تبدیل می‌شود.

عناصر فرزند <Add> از جایگزینی رشته پویا پشتیبانی می‌کنند که به آن قالب‌بندی پیام می‌گویند.

‫<FormParams> (فرزند <Add>)

پارامترهای فرم جدیدی به پیام درخواست اضافه می‌کند. این عنصر تأثیری بر پیام پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <FormParam> عنصر
عنصر ولی <Add>
عناصر فرزند <FormParam>

عنصر <FormParams> از نحو زیر استفاده می‌کند:

نحوs5

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

مثال ۱s6

مثال زیر یک پارامتر فرم واحد («پاسخ») و یک مقدار ایستا («۴۲») را به درخواست اضافه می‌کند:

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

نمونه ۲s7

مثال زیر مقدار پارامتر پُرسمان name را دریافت می‌کند و آن را به‌عنوان پارامتر فرم به درخواست اضافه می‌کند، و سپس پارامتر پُرسمان را برمی‌دارد:

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

توجه داشته باشید که این مثال هدفی را با <AssignTo> مشخص نمی‌کند. این خط‌مشی پارامتر را فقط به درخواست اضافه می‌کند.

مثال ۳s8

مثال زیر چندین پارامتر فرم را به درخواست اضافه می‌کند:

<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 درخواست اصلاح‌شده را به نقطه پایانی هدف ارسال خواهد کرد.

می‌توانید از ابزار Trace برای مشاهده جریان استفاده کنید. خواهید دید که بدنه درخواست حاوی داده‌های فرم کدگذاری‌شده با نشانی وب است که در ابتدا به‌عنوان پارامترهای رشته پُرسمان ارسال شده است:

username=nick&zip_code=90210&default_language=en

فقط زمانی می‌توانید از <FormParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ POST
  • نوع پیام: درخواست
  • یکی (یا هر دو) از موارد زیر:
    • داده‌های فرم: روی مقداری تنظیم شده است، یا «» (رشته خالی). برای مثال، با curl، -d "" را به درخواستتان اضافه کنید.
    • سرصفحه Content-Length: روی ۰ تنظیم کنید (اگر داده‌ای در درخواست اصلی وجود ندارد؛ درغیراین‌صورت، طول فعلی، برحسب بایت). برای مثال، با curl -H "Content-Length: 0" را به درخواستتان اضافه کنید.

برای مثال:

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

وقتی <FormParams> را اضافه می‌کنید، Edge سرایند Content-Type درخواست را روی «application/x-www-form-urlencoded» تنظیم می‌کند و سپس پیام را به سرویس هدف ارسال می‌کند.

‫<Headers> (فرزند <Add>)

سراینده‌های جدیدی به درخواست یا پاسخ مشخص‌شده اضافه می‌کند که توسط عنصر <AssignTo> مشخص شده است.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <Header> عنصر
عنصر ولی <Add>
عناصر فرزند <Header>

عنصر <Headers> از نحو زیر استفاده می‌کند:

نحوs9

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

نمونه ۱s10

مثال زیر سرصفحه partner-id را به پیام درخواست اضافه می‌کند و مقدار متغیر جریان verifyapikey.VAK-1.developer.app.partner-id را به آن سرصفحه اختصاص می‌دهد.

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

‫<QueryParams> (فرزند <Add>)

پارامترهای پُرسمان جدیدی به درخواست اضافه می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <QueryParam> عنصر
عنصر ولی <Add>
عناصر فرزند <QueryParam>

عنصر <QueryParams> از نحو زیر استفاده می‌کند:

نحوs11

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

نمونه ۱s12

مثال زیر پارامتر پُرسمان «myParam» را به درخواست اضافه می‌کند و مقدار «42» را به آن اختصاص می‌دهد:

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

فقط زمانی می‌توانید از <QueryParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ GET
  • نوع پیام: درخواست

علاوه‌براین، فقط زمانی می‌توانید پارامترهای پُرسمان را تنظیم کنید که مشخصه type عنصر <AssignTo> پیام درخواست باشد. تنظیم آن‌ها در پاسخ هیچ تأثیری ندارد.

اگر آرایه خالی از پارامترهای پُرسمان در خط‌مشی‌تان تعریف کنید (<Add><QueryParams/></Add>)، خط‌مشی هیچ پارامتر پُرسمانی اضافه نمی‌کند. این کار مانند حذف <QueryParams> است.

<AssignTo>

تعیین می‌کند که خط‌مشی AssignMessage روی کدام شیء اعمال شود. گزینه‌ها عبارت‌اند از:

  • پیام درخواست: request دریافت‌شده توسط پراکسی میانای برنامه‌سازی کاربردی
  • پیام پاسخ: response از سرور هدف برگردانده شد
  • پیام سفارشی: شیء درخواست یا پاسخ سفارشی

توجه داشته باشید که در برخی موارد، نمی‌توانید شیئی را که خط‌مشی AssignMessage روی آن اعمال می‌شود تغییر دهید. برای مثال، نمی‌توانید از <Add> یا <Set> برای افزودن یا تغییر پارامترهای پُرسمان (<QueryParams>) یا پارامترهای فرم (<FormParams>) در پاسخ استفاده کنید. فقط می‌توانید پارامترهای پُرسمان و پارامترهای فرم را در درخواست دستکاری کنید.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <AssignMessage>
عناصر فرزند هیچ‌کدام

اگر <AssignTo> را مشخص نکنید، یا اگر عنصر <AssignTo> را مشخص کنید، اما مقدار نوشتاری برای عنصر مشخص نکنید، خط‌مشی روی درخواست یا پاسخ پیش‌فرض عمل می‌کند که براساس جایی است که خط‌مشی اجرا می‌شود. اگر خط‌مشی در جریان درخواست اجرا شود، بر پیام درخواست تأثیر می‌گذارد. اگر در جریان پاسخ اجرا شود، خط‌مشی به‌طور پیش‌فرض بر پاسخ تأثیر می‌گذارد.

عنصر <AssignTo> از نحو زیر استفاده می‌کند:

نحوs13

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

مثال ۱s14

مثال زیر مشخص می‌کند که هدف، درخواست اصلی است که به نقطه پایانی هدف ارسال خواهد شد:

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

نمونه ۲s15

مثال زیر شیء درخواست جدیدی ایجاد می‌کند:

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

وقتی شیء درخواست یا پاسخ جدیدی ایجاد می‌کنید، عناصر دیگر خط‌مشی AssignMessage (مانند <Add>، <Set>، و <Copy>) روی آن شیء درخواست جدید عمل می‌کنند.

می‌توانید بعداً در جریان به شیء درخواست جدید در خط‌مشی‌های دیگر دسترسی پیدا کنید یا شیء درخواست جدید را با خط‌مشی ServiceCallout به سرویس خارجی ارسال کنید.

مثال ۳s16

مثال زیر یک شیء درخواست جدید به‌نام «MyRequestObject» ایجاد می‌کند:

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

وقتی شیء درخواست یا پاسخ جدیدی ایجاد می‌کنید، عناصر دیگر خط‌مشی AssignMessage (مانند <Add>، <Set>، و <Copy>) روی آن شیء درخواست جدید عمل می‌کنند.

می‌توانید بعداً در جریان به شیء درخواست جدید در خط‌مشی‌های دیگر دسترسی پیدا کنید یا شیء درخواست جدید را با خط‌مشی ServiceCallout به سرویس خارجی ارسال کنید.

جدول زیر مشخصه‌های <AssignTo> را شرح می‌دهد:

مشخصه شرح الزامی است؟ نوع
createNew

تعیین می‌کند که آیا این خط‌مشی هنگام اختصاص دادن مقادیر، پیام جدیدی ایجاد می‌کند یا نه.

اگر «true» باشد، خط‌مشی متغیر جدیدی از نوع مشخص‌شده توسط type (یا «request» یا «response») ایجاد می‌کند. اگر نام متغیر جدید را مشخص نکنید، خط‌مشی شیء درخواست یا پاسخ جدیدی براساس مقدار type ایجاد می‌کند.

اگر «نادرست» باشد، خط‌مشی به یکی از دو روش زیر پاسخ می‌دهد:

  • اگر <AssignTo> بتواند نام متغیر را به درخواست یا پاسخ تبدیل کند، پردازش ادامه می‌یابد. برای مثال، اگر خط‌مشی در جریان درخواست باشد، متغیر شیء درخواست است. اگر خط‌مشی در پاسخ باشد، متغیر شیء پاسخ است.
  • اگر <AssignTo> قابل‌حل نباشد یا به نوع غیرپیام حل شود، دراین‌صورت خط‌مشی خطا می‌دهد.

اگر createNew مشخص نشده باشد، خط‌مشی به یکی از دو روش زیر پاسخ می‌دهد:

  • اگر مقدار نوشتاری <AssignTo> به پیام تبدیل شود، پردازش به مرحله بعدی می‌رود.
  • اگر مقدار نوشتاری <AssignTo> قابل‌حل نباشد، یا به نوع غیرپیام حل شود، متغیر جدیدی از نوع مشخص‌شده در type ایجاد می‌شود.
اختیاری بولی
transport

نوع انتقال را برای نوع پیام درخواست یا پاسخ مشخص می‌کند.

مقدار پیش‌فرض «http» است (تنها مقدار پشتیبانی‌شده).

اختیاری رشته
type وقتی createNew «درست» باشد، نوع پیام جدید را مشخص می‌کند. مقادیر معتبر «درخواست» یا «پاسخ» است.

اگر این مشخصه را حذف کنید، Edge بسته به اینکه این خط‌مشی در کجای جریان اجرا می‌شود، درخواست یا پاسخ ایجاد می‌کند.

اختیاری رشته

<AssignVariable>

مقداری را به متغیر جریان اختصاص می‌دهد. اگر متغیر جریان وجود نداشته باشد، <AssignVariable> آن را ایجاد می‌کند.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن نوع پیچیده
عنصر ولی <AssignMessage>
عناصر فرزند <Name> (الزامی)
<Ref>
<Template>
<Value>

مقداری که به متغیر جریان اختصاص می‌دهید می‌تواند یکی از موارد زیر باشد:

  • رشته حرفی: از عنصر فرزند <Value> برای مشخص کردن مقدار رشته حرفی برای متغیر جریان استفاده کنید.
  • متغیر جریان: از عنصر فرزند <Ref> برای مشخص کردن مقدار یک متغیر جریان موجود برای متغیر جریان مقصد استفاده کنید. برای مشاهده فهرست کامل متغیرهای جریان که می‌توانند به‌عنوان منبع استفاده شوند، به مرجع متغیرهای جریان مراجعه کنید.
  • الگوی پیام: از عنصر فرزند <Template> برای مشخص کردن الگوی پیام برای درون‌یابی استفاده کنید تا مقدار را برای قرار دادن در متغیر جریان مقصد دریافت کنید.

عنصر <AssignVariable> از نحو زیر استفاده می‌کند:

نحوs17

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

از عنصر <Ref> برای مشخص کردن متغیر منبع استفاده کنید. اگر متغیر ارجاع‌شده توسط <Ref> دردسترس نباشد، Edge از مقدار مشخص‌شده توسط عنصر <Value> استفاده می‌کند. اگر <Template> را تعریف کنید، بر عناصر فرزند دیگر اولویت دارد.

مثال ۱s18

مثال زیر مقدار متغیر جدید myvar را روی مقدار دقیق «42» تنظیم می‌کند:

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

نمونه ۲s19

مثال زیر مقدار متغیر جریان request.header.user-agent را به متغیر جریان مقصد myvar و مقدار پارامتر پُرسمان country را به متغیر جریان مقصد Country اختصاص می‌دهد:

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

اگر هریک از واگذاری‌ها ناموفق باشد، Edge به‌جای آن مقدار «ErrorOnCopy» را به متغیر جریان مقصد واگذار می‌کند.

اگر متغیرهای جریان myvar یا Country وجود نداشته باشند، <AssignVariable> آن‌ها را ایجاد می‌کند.

مثال ۳s20

مثال زیر از عنصر فرزند <Template> برای الحاق دو متغیر بافت با یک رشته تحت‌اللفظی (خط تیره) بین آن‌ها استفاده می‌کند:

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

یک کاربرد رایج برای <AssignVariable> تنظیم مقدار پیش‌فرض برای پارامتر پُرسمان، سرصفحه، یا مقدار دیگری است که می‌تواند با درخواست ارسال شود. این کار را با ترکیبی از هر دو عنصر فرزند <Ref> و <Value> انجام می‌دهید. برای اطلاعات بیشتر، مثال‌های مربوط به <Ref> را ببینید.

‫<Name> (فرزند <AssignVariable>)

نام متغیر جریان مقصد را مشخص می‌کند (مثلاً متغیری که مقدار آن توسط خط‌مشی AssignMessage تنظیم شده است). اگر متغیر نام‌گذاری‌شده در <AssignVariable> وجود نداشته باشد، خط‌مشی متغیری با آن نام ایجاد می‌کند.

مقدار پیش‌فرض نامربوط
الزامی است؟ الزامی
تایپ کردن رشته
عنصر ولی <AssignVariable>
عناصر فرزند هیچ‌کدام

عنصر <Name> از نحو زیر استفاده می‌کند:

نحوs21

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

نمونه ۱s22

مثال زیر متغیر مقصد را به‌عنوان myvar مشخص می‌کند و آن را روی مقدار دقیق «۴۲» تنظیم می‌کند:

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

اگر myvar وجود نداشته باشد، <AssignVariable> آن را ایجاد می‌کند.

‫<Ref> (فرزند <AssignVariable>)

منبع واگذاری را به‌عنوان متغیر جریان مشخص می‌کند. متغیر جریان می‌تواند یکی از متغیرهای جریان ازپیش تعریف‌شده (همان‌طور که در مرجع متغیرهای جریان فهرست شده است) یا متغیر جریان سفارشی باشد که شما ایجاد کرده‌اید.

مقدار <Ref> همیشه به‌عنوان متغیر جریان تفسیر می‌شود؛ نمی‌توانید رشته تحت‌اللفظی را به‌عنوان مقدار مشخص کنید. برای اختصاص دادن مقدار رشته‌ای تحت‌اللفظی، به‌جای آن از عنصر <Value> استفاده کنید.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <AssignVariable>
عناصر فرزند هیچ‌کدام

وقتی متغیر جریان را با <Ref> مشخص می‌کنید، کروشه‌های دربرگیرنده «{}» را که معمولاً برای ارجاع به متغیر جریان استفاده می‌کنید حذف کنید. برای مثال، برای تنظیم مقدار متغیر جدیدتان روی مقدار متغیر جریان client.host:

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

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

برای تعریف مقدار پیش‌فرض برای متغیر جریان مقصد، از <Value> در ترکیب با <Ref> استفاده کنید. اگر متغیر جریان مشخص‌شده توسط <Ref> وجود نداشته باشد، قابل‌خواندن نباشد، یا تهی باشد، Edge مقدار <Value> را به متغیر جریان مقصد اختصاص می‌دهد.

عنصر <Ref> از نحو زیر استفاده می‌کند:

نحو

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

مثال ۱s23

مثال زیر مقدار متغیر جریان request.header.user-agent را به متغیر جریان مقصد myvar و مقدار پارامتر پُرسمان country را به متغیر Country اختصاص می‌دهد:

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

در این مثال، Edge مقدار پیش‌فرض (یا مقدار جایگزین) برای هیچ‌کدام از واگذاری‌ها ندارد.

مثال ۲s23

مثال زیر مقدار متغیر جریان request.header.user-agent را به متغیر جریان مقصد myvar و مقدار پارامتر پُرسمان country را به متغیر Country اختصاص می‌دهد:

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

در این مثال، اگر مقادیر متغیر جریان request.header.user-agent یا پارامتر پُرسمان Country تهی، غیرقابل‌خواندن، یا بدشکل باشد، Edge مقدار «ErrorOnCopy» را به متغیرهای جدید اختصاص می‌دهد.

مثال ۳s24

یک مورد استفاده رایج برای <AssignVariable> تنظیم مقدار پیش‌فرض یک پارامتر پُرسمان، سرصفحه، یا مقدار دیگری است که می‌تواند با درخواست ارسال شود. برای مثال، شما یک پراکسی API آب‌وهوا ایجاد می‌کنید که در آن درخواست یک پارامتر پُرسمان واحد به نام «w» را می‌گیرد. این پارامتر حاوی شناسه شهری است که می‌خواهید آب‌وهوای آن را بدانید. نشانی وب درخواست این قالب را دارد:

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 را دریافت می‌کند و آن را به خودش اختصاص می‌دهد. اگر متغیر جریان تهی باشد، یعنی پارامتر پُرسمان «w» از درخواست حذف شده باشد، این نمونه از مقدار پیش‌فرض عنصر <Value> استفاده می‌کند. بنابراین، می‌توانید درخواستی به این پراکسی میانای برنامه‌سازی کاربردی ارسال کنید که پارامتر پُرسمان «w» را حذف می‌کند:

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

...و همچنان پراکسی میانای برنامه‌سازی کاربردی نتیجه معتبری برگرداند.

برخلاف زمانی‌که از <Value> استفاده می‌کنید، مقدار <Ref> باید یک متغیر جریان باشد، مثلاً ویژگی یک شیء request، response، یا target. این مقدار می‌تواند متغیر جریان سفارشی‌ای باشد که ایجاد کرده‌اید.

اگر متغیر جریانی را مشخص کنید که برای مقدار <Ref> وجود ندارد، و مقدار <IgnoreUnresolvedVariables> «true» باشد، Edge خطا می‌دهد.

‫<Template> (فرزند <AssignVariable>)

الگوی پیام را مشخص می‌کند. الگوی پیام به شما امکان می‌دهد هنگام اجرای خط‌مشی، جایگزینی رشته متغیر را انجام دهید و می‌توانید رشته‌های تحت‌اللفظی را با نام‌های متغیر که در آکولاد قرار گرفته‌اند ترکیب کنید. علاوه‌براین، الگوهای پیام از توابعی مثل گریز و تبدیل حروف پشتیبانی می‌کنند.

از مشخصه ref برای تعیین متغیر جریان استفاده کنید که مقدار متغیر یک الگوی پیام است. برای مثال، می‌توانید الگوی پیام را به‌عنوان ویژگی سفارشی در برنامه توسعه‌دهنده ذخیره کنید. وقتی Edge برنامه توسعه‌دهنده را پس‌از درستی‌سنجی کلید میانای API یا توکن امنیتی (ازطریق خط‌مشی اضافی) شناسایی می‌کند، عنصر <AssignVariable> می‌تواند از الگوی پیام از ویژگی سفارشی برنامه استفاده کند، که به‌عنوان متغیر جریان از خط‌مشی امنیتی دردسترس است.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <AssignVariable>
عناصر فرزند هیچ‌کدام

عنصر <Template> از نحو زیر استفاده می‌کند:

نحوs25

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

مثال ۱s26

مثال زیر از نحو قالب‌بندی پیام برای الحاق دو متغیر بافت با یک رشته تحت‌اللفظی (خط تیره) بین آن‌ها استفاده می‌کند:

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

نمونه ۲s27

مثال زیر متغیر جریان را مشخص می‌کند، که در آن مقدار متغیر یک الگوی پیام ازپیش تعریف‌شده است. اگر می‌خواهید الگوی ازپیش تعریف‌شده‌ای را در زمان اجرا بدون نیاز به اصلاح خط‌مشی تزریق کنید، از این گزینه استفاده کنید:

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

مثال ۳s28

مثال زیر یک متغیر جریان و یک مقدار نوشتاری را مشخص می‌کند. در این حالت، اگر متغیر ارجاع‌شده غیرتهی باشد، از آن مقدار به‌عنوان الگو استفاده می‌شود. اگر مقدار ارجاع‌شده تهی باشد، مقدار نوشتار (در این مورد، {system.uuid}-{messageid}) به‌عنوان الگو استفاده می‌شود. این الگو برای ارائه مقدار «لغو» مفید است، جایی که در برخی موارد می‌خواهید الگوی پیش‌فرض (بخش نوشتاری) را با مقادیری که به‌طور پویا تنظیم شده‌اند لغو کنید. برای مثال، یک عبارت شرطی ممکن است مقداری را از نگاشت مقدار-کلید بگیرد و متغیر ارجاع‌شده را روی آن مقدار تنظیم کند:

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

‫<Value> (فرزند <AssignVariable>)

مقدار متغیر جریان مقصد را که با <AssignVariable> تنظیم شده است تعریف می‌کند. مقدار همیشه به‌عنوان رشته تحت‌اللفظی تفسیر می‌شود؛ نمی‌توانید از متغیر جریان به‌عنوان مقدار استفاده کنید، حتی اگر مقدار را در کروشه («{}») قرار دهید. برای استفاده از متغیر جریان، به‌جای آن از <Ref> استفاده کنید.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <AssignVariable>
عناصر فرزند هیچ‌کدام

وقتی در ترکیب با عنصر <Ref> استفاده می‌شود، <Value> به‌عنوان مقدار پیش‌فرض (یا جایگزین) عمل می‌کند. اگر <Ref> مشخص نشده باشد، غیرقابل‌حل باشد، یا تهی باشد، از مقدار <Value> استفاده می‌شود.

عنصر <Value> از نحو زیر استفاده می‌کند:

نحوs29

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

مثال ۱

مثال زیر مقدار متغیر جریان مقصد، myvar، را روی مقدار دقیق «42» تنظیم می‌کند:

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

مثال ۲

مثال زیر مقدار متغیر جریان request.header.user-agent را به متغیر جریان myvar و مقدار پارامتر پُرسمان country را به متغیر Country اختصاص می‌دهد:

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

اگر هریک از واگذاری‌ها ناموفق باشد، <AssignVariable> درعوض مقدار «ErrorOnCopy» را به متغیر جریان مقصد واگذار می‌کند.

<Copy>

مقادیر را از پیام مشخص‌شده با مشخصه source به پیام مشخص‌شده با عنصر <AssignTo> کپی می‌کند. اگر هدفی را با <AssignTo> مشخص نکنید، این خط‌مشی مقادیر را در درخواست یا پاسخ کپی می‌کند، بسته به اینکه این خط‌مشی در کجای جریان اجرا می‌شود.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <AssignMessage>
عناصر فرزند <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

اگر هیچ عنصر فرعی‌ای را زیر عنصر <Copy> مشخص نکنید، همه بخش‌های پیام منبع تعیین‌شده را کپی می‌کند.

عنصر <Copy> از نحو زیر استفاده می‌کند:

نحوs30

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

نمونه ۱s31

مثال زیر یک سرصفحه، سه پارامتر فرم، مسیر، و همه پارامترهای پُرسمان را از پیام 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> وجود ندارند، خط‌مشی آن بخش‌های پیام را کپی نمی‌کند.

مثال ۲s32

مثال زیر ابتدا همه چیز را در پیام response موجود حذف می‌کند، سپس همه مقادیر را از پیام دیگری به‌نام secondResponse در پیام response کپی می‌کند:

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

عنصر <Copy> یک مشخصه دارد:

مشخصه شرح الزامی است؟ نوع
منبع

شیء منبع کپی را مشخص می‌کند.

  • اگر source مشخص نشده باشد، به‌طور پیش‌فرض روی message تنظیم می‌شود که بسته به جریانی که خط‌مشی در آن اجرا می‌شود، مقدار متفاوتی می‌گیرد. اگر خط‌مشی در جریان درخواست اجرا شود، متغیر message به شیء request ارجاع می‌دهد. اگر خط‌مشی در جریان پاسخ اجرا شود، متغیر message به شیء response ارجاع می‌دهد.
  • اگر متغیر منبع قابل‌حل نباشد یا به نوع غیرپیام حل شود، <Copy> پاسخ نمی‌دهد.
اختیاری رشته

‫<FormParams> (فرزند <Copy>)

پارامترهای فرم را از درخواست مشخص‌شده توسط مشخصه source عنصر <Copy> به درخواست مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <FormParam> عنصر یا آرایه‌ای خالی
عنصر ولی <Copy>
عناصر فرزند <FormParam>

عنصر <FormParams> از نحو زیر استفاده می‌کند:

نحوs33

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

مثال ۱s34

مثال زیر یک پارامتر فرم را از درخواست به درخواست سفارشی «MyCustomRequest» کپی می‌کند:

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

نمونه ۲s35

مثال زیر همه پارامترهای فرم را در درخواست سفارشی «MyCustomRequest» کپی می‌کند:

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

مثال ۳s36

مثال زیر سه پارامتر فرم را در درخواست سفارشی «MyCustomRequest» کپی می‌کند:

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

مثال ۴s37

اگر چند پارامتر فرم با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

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

این مثال «f1»،‏ «f2»، و مقدار دوم «f3» را کپی می‌کند. اگر «f3» فقط یک مقدار داشته باشد، کپی نمی‌شود.

فقط زمانی می‌توانید از <FormParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ POST
  • نوع پیام: پاسخ
  • یکی (یا هر دو) از موارد زیر:
    • داده‌های فرم: روی مقداری تنظیم شده است، یا «» (رشته خالی). برای مثال، با curl، -d "" را به درخواستتان اضافه کنید.
    • سرصفحه Content-Length: روی ۰ تنظیم کنید (اگر داده‌ای در درخواست اصلی وجود ندارد؛ درغیراین‌صورت، طول فعلی). برای مثال، با curl -H "Content-Length: 0" را به درخواستتان اضافه کنید.

وقتی <FormParams> را کپی می‌کنید، <Copy> Content-Type پیام را روی «application/x-www-form-urlencoded» تنظیم می‌کند و سپس پیام را به سرویس هدف ارسال می‌کند.

‫<Headers> (فرزند <Copy>)

سرصفحه‌های HTTP را از پیام درخواست یا پاسخ مشخص‌شده توسط مشخصه source عنصر <Copy> به پیام درخواست یا پاسخ مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <Header> عنصر یا آرایه‌ای خالی
عنصر ولی <Copy>
عناصر فرزند <Header>

عنصر <Headers> از نحو زیر استفاده می‌کند:

نحوs38

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

مثال ۱s39

مثال زیر سرصفحه user-agent را از درخواست به شیء درخواست سفارشی جدید کپی می‌کند:

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

نمونه ۲s40

برای کپی کردن همه سرصفحه‌ها، از عنصر <Headers> خالی استفاده کنید، همان‌طور که در مثال زیر نشان داده شده است:

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

مثال ۳s41

اگر چند سرایند با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

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

این مثال «h1»،‏ «h2»، و مقدار دوم «h3» را کپی می‌کند. اگر «h3» فقط یک مقدار داشته باشد، کپی نمی‌شود.

‫<Path> (فرزند <Copy>)

تعیین می‌کند که آیا مسیر باید از درخواست منبع به درخواست مقصد کپی شود یا نه. این عنصر تأثیری بر پاسخ ندارد.

اگر «درست» باشد، این خط‌مشی مسیر را از پیام درخواست مشخص‌شده توسط مشخصه source عنصر <Copy> به پیام درخواست مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <Path> از نحو زیر استفاده می‌کند:

نحو

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

نمونه ۱s42

مثال زیر نشان می‌دهد که خط‌مشی AssignMessage باید مسیر را از درخواست منبع در شیء درخواست سفارشی جدید کپی کند:

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

فقط زمانی می‌توانید از <Path> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست

‫<Payload> (فرزند <Copy>)

تعیین می‌کند که آیا بار مفید باید از منبع به مقصد کپی شود یا نه. مبدأ و مقصد می‌توانند درخواست یا پاسخ باشند.

اگر «true» باشد، این خط‌مشی بار مفید را از پیام مشخص‌شده توسط مشخصه source عنصر <Copy> به پیام مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <Payload> از نحو زیر استفاده می‌کند:

نحوs43

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

مثال ۱s44

مثال زیر <Payload> را روی «true» تنظیم می‌کند تا بار داده درخواست از درخواست به پاسخ کپی شود:

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

‫<QueryParams> (فرزند <Copy>)

پارامترهای رشته پُرسمان را از درخواست مشخص‌شده توسط مشخصه source عنصر <Copy> به درخواست مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <QueryParam> عنصر یا آرایه‌ای خالی
عنصر ولی <QueryParam>
عناصر فرزند هیچ‌کدام

عنصر <QueryParams> از نحو زیر استفاده می‌کند:

نحوs45

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

مثال ۱s46

مثال زیر پارامتر پُرسمان «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>

نمونه ۲s47

مثال زیر همه پارامترهای پُرسمان را از درخواست در یک شیء درخواست سفارشی جدید کپی می‌کند:

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

مثال ۳s48

اگر چند پارامتر پُرسمان با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

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

این مثال «qp1»،‏ «qp2»، و مقدار دوم «qp3» را کپی می‌کند. اگر «qp3» فقط یک مقدار داشته باشد، کپی نمی‌شود.

فقط زمانی می‌توانید از <QueryParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ GET
  • نوع پیام: درخواست

‫<ReasonPhrase> (فرزند <Copy>)

تعیین می‌کند که آیا عبارت دلیل باید از پاسخ منبع به پاسخ مقصد کپی شود یا نه. این عنصر تأثیری بر درخواست ندارد.

اگر «true» باشد، این خط‌مشی ReasonPhrase را از پاسخی که با مشخصه source عنصر <Copy> مشخص شده است به پاسخی که با عنصر <AssignTo> مشخص شده است کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <ReasonPhrase> از نحو زیر استفاده می‌کند:

نحوs49

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

مثال ۱s50

مثال زیر <ReasonPhrase> را روی true تنظیم می‌کند. با منبع و عنصر <AssignTo> همان‌طور که مشخص شده است، این باعث می‌شود <Copy> عبارت دلیل را از پیام پاسخ نام‌گذاری‌شده در شیء response کپی کند:

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

فقط زمانی می‌توانید از <ReasonPhrase> استفاده کنید که پیام‌های مبدأ و مقصد از نوع «پاسخ» باشند.

‫<StatusCode> (فرزند <Copy>)

تعیین می‌کند که آیا کد وضعیت از پاسخ منبع به پاسخ مقصد کپی می‌شود یا نه. این عنصر تأثیری بر درخواست ندارد.

اگر «true» باشد، این خط‌مشی کد وضعیت را از پیام پاسخ مشخص‌شده توسط مشخصه source عنصر <Copy> به پیام پاسخ مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <StatusCode> از نحو زیر استفاده می‌کند:

نحوs52

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

نمونه ۱s53

مثال زیر <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> این است که کد وضعیت پاسخ پراکسی را روی مقداری متفاوت از مقدار دریافتی از هدف تنظیم کند.

‫<Verb> (فرزند <Copy>)

تعیین می‌کند که آیا فعل HTTP از درخواست منبع به درخواست مقصد کپی می‌شود یا نه. این عنصر تأثیری بر پاسخ ندارد.

اگر «درست» باشد، فعل یافت‌شده در مشخصه source عنصر <Copy> را در درخواست مشخص‌شده در عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <Verb> از نحو زیر استفاده می‌کند:

نحوs54

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

مثال ۱s55

مثال زیر <Verb> را روی «true» تنظیم می‌کند که فعل را از درخواست پیش‌فرض در درخواست سفارشی جدید کپی می‌کند:

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

فقط زمانی می‌توانید از <Verb> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست

‫<Version> (فرزند <Copy>)

تعیین می‌کند که آیا نسخه HTTP از درخواست منبع به درخواست مقصد کپی شده است یا نه. این عنصر تأثیری بر پاسخ ندارد.

اگر «درست» باشد، نسخه HTTP یافت‌شده در مشخصه source عنصر <Copy> را در شیء مشخص‌شده توسط عنصر <AssignTo> کپی می‌کند.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Copy>
عناصر فرزند هیچ‌کدام

عنصر <Version> از نحو زیر استفاده می‌کند:

نحوs56

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

مثال ۱s57

مثال زیر <Version> را در درخواست روی «true» تنظیم می‌کند، که نسخه را از شیء درخواست پیش‌فرض به شیء درخواست سفارشی جدیدی کپی می‌کند:

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

فقط زمانی می‌توانید از <Version> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست

<DisplayName>

علاوه‌بر مشخصه name، از این مشخصه برای برچسب‌گذاری خط‌مشی در ویرایشگر پراکسی میانای کاربر مدیریت با نامی متفاوت و طبیعی‌تر استفاده کنید.

عنصر <DisplayName> برای همه خط‌مشی‌ها مشترک است.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری. اگر <DisplayName> را حذف کنید، مقدار مشخصه name خط‌مشی استفاده می‌شود
تایپ کردن رشته
عنصر ولی <PolicyElement>
عناصر فرزند هیچ‌کدام

عنصر <DisplayName> از نحو زیر استفاده می‌کند:

نحو

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

مثال

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

عنصر <DisplayName> هیچ مشخصه یا عنصر فرزندی ندارد.

<IgnoreUnresolvedVariables>

تعیین می‌کند که آیا پردازش هنگام مواجهه با متغیر حل‌نشده متوقف شود یا نه.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <AssignMessage>
عناصر فرزند هیچ‌کدام

روی true تنظیم کنید تا متغیرهای حل‌نشده نادیده گرفته شوند و پردازش ادامه یابد؛ درغیراین‌صورت false. مقدار پیش‌فرض false است.

تنظیم <IgnoreUnresolvedVariables> روی true با تنظیم continueOnError <AssignMessage> روی true متفاوت است زیرا این تنظیم مختص تنظیم و دریافت مقادیر متغیرها است. اگر continueOnError را روی true تنظیم کنید، Edge همه خطاها را نادیده می‌گیرد، نه فقط خطاهایی که هنگام استفاده از متغیرها با آن‌ها مواجه می‌شوید.

عنصر <IgnoreUnresolvedVariables> از نحو زیر استفاده می‌کند:

نحوs58

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

مثال ۱s59

مثال زیر <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>

سرصفحه‌ها، پارامترهای پُرسمان، پارامترهای فرم، و/یا بار پیام را از پیام برمی‌دارد. پیام می‌تواند درخواست یا پاسخ باشد. بااستفاده از عنصر <AssignTo> مشخص می‌کنید که <Remove> روی کدام پیام عمل می‌کند.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن نوع پیچیده
عنصر ولی <AssignMessage>
عناصر فرزند <FormParams>
<Headers>
<Payload>
<QueryParams>

یک مورد استفاده رایج برای <Remove> حذف پارامتر پُرسمان یا سرصفحه حاوی اطلاعات حساس از شیء درخواست ورودی است تا از ارسال آن به سرور زیرینه جلوگیری شود.

عنصر <Remove> از نحو زیر استفاده می‌کند:

نحوs60

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

مثال ۱s61

مثال زیر متن پیام را از پاسخ برمی‌دارد:

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

در جریان پاسخ، این خط‌مشی بدنه پاسخ را برمی‌دارد و فقط سرصفحه‌های HTTP را به کارخواه برمی‌گرداند.

نمونه ۲s62

مثال زیر همه پارامترهای فرم و پارامتر پُرسمان را از شیء request برمی‌دارد:

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

مثال ۳s63

مثال زیر همه چیز را از شیء پیام برمی‌دارد:

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

معمولاً این کار را فقط درصورتی انجام می‌دهید که بخواهید از عنصر <Set> یا عنصر <Copy> برای تنظیم برخی مقادیر جایگزین در پیام استفاده کنید.

‫<FormParams> (فرزند <Remove>)

پارامترهای فرم مشخص‌شده را از درخواست برمی‌دارد. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <FormParam> عنصر یا آرایه‌ای خالی
عنصر ولی <Remove>
عناصر فرزند <FormParam>

عنصر <FormParams> از نحو زیر استفاده می‌کند:

نحوs64

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

مثال ۱s65

مثال زیر سه پارامتر فرم را از درخواست حذف می‌کند:

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

مثال ۲s66

مثال زیر همه پارامترهای فرم را از درخواست برمی‌دارد:

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

مثال ۳s67

اگر چند پارامتر فرم با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

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

این مثال «f1»،‏ «f2»، و مقدار دوم «f3» را برمی‌دارد. اگر «f3» فقط یک مقدار داشته باشد، حذف نمی‌شود.

فقط زمانی می‌توانید از <FormParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست
  • Content-Type: "application/x-www-form-urlencoded"

‫<Headers> (فرزند <Remove>)

سرصفحه‌های HTTP مشخص‌شده را از درخواست یا پاسخ حذف می‌کند، که توسط عنصر <AssignTo> مشخص شده است.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <Header> عنصر یا آرایه‌ای خالی
عنصر ولی <Remove>
عناصر فرزند <Header>

عنصر <Headers> از نحو زیر استفاده می‌کند:

نحو

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

مثال ۱s68

مثال زیر سرصفحه user-agent را از درخواست برمی‌دارد:

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

مثال ۲s69

مثال زیر همه سرصفحه‌ها را از درخواست برمی‌دارد:

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

مثال ۳s70

اگر چند سرایند با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

<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> بار مفید را در درخواست یا پاسخ حذف می‌کند یا نه، که توسط عنصر <AssignTo> مشخص می‌شود. برای پاک کردن بار مفید، روی «درست» تنظیم کنید؛ درغیراین‌صورت، روی «نادرست» تنظیم کنید. مقدار پیش‌فرض «false» است.

مقدار پیش‌فرض نادرست
الزامی است؟ اختیاری
تایپ کردن بولی
عنصر ولی <Remove>
عناصر فرزند هیچ‌کدام

عنصر <Payload> از نحو زیر استفاده می‌کند:

نحو

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

مثال ۱s71

مثال زیر <Payload> را روی «true» تنظیم می‌کند تا بار داده درخواست پاک شود:

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

‫<QueryParams> (فرزند <Remove>)

پارامترهای پُرسمان مشخص‌شده را از درخواست برمی‌دارد. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه‌ای از <QueryParam> عنصر یا آرایه‌ای خالی
عنصر ولی <Remove>
عناصر فرزند <QueryParam>

عنصر <QueryParams> از نحو زیر استفاده می‌کند:

نحوs72

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

مثال ۱s73

مثال زیر یک پارامتر پرسمان را از درخواست برمی‌دارد:

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

مثال ۲s74

مثال زیر همه پارامترهای پُرسمان را از درخواست برمی‌دارد:

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

مثال ۳s75

اگر چند پارامتر پُرسمان با نام یکسان وجود دارد، از نحو زیر استفاده کنید:

<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» فقط یک مقدار داشته باشد، حذف نمی‌شود.

مثال ۴s76

مثال زیر پارامتر پرسمان apikey را از درخواست برمی‌دارد:

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

فقط زمانی می‌توانید از <QueryParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ GET
  • نوع پیام: درخواست

<Set>

اطلاعات را در پیام درخواست یا پاسخ تنظیم می‌کند که با عنصر <AssignTo> مشخص می‌شود. <Set> سرایندها یا پارامترهای پُرسمان یا فرمی را که ازقبل در پیام اصلی وجود دارد رونویسی می‌کند. سرصفحه‌ها و پُرسمان و پارامترهای فرم در پیام HTTP ممکن است حاوی چند مقدار باشد. برای افزودن مقادیر بیشتر برای سرصفحه یا پارامتر، به‌جای آن از عنصر <Add> استفاده کنید.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن نوع پیچیده
عنصر ولی <AssignMessage>
عناصر فرزند <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

عنصر <Set> از نحو زیر استفاده می‌کند:

نحو

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

مثال ۱s77

مثال زیر سرصفحه خاصی را تنظیم می‌کند. وقتی این خط‌مشی در جریان «درخواست» پیوست شود، به سیستم بالادستی اجازه می‌دهد سرصفحه دیگری را که در درخواست ورودی اصلی گنجانده نشده است دریافت کند.

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

مثال ۲s78

مثال زیر بار داده را برای پاسخ و همچنین سرصفحه Content-Type بازنویسی می‌کند.

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

‫<FormParams> (فرزند <Set>)

پارامترهای فرم موجود در درخواست را بازنویسی می‌کند و آن‌ها را با مقادیر جدیدی که با این عنصر مشخص می‌کنید جایگزین می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <FormParam> عنصر
عنصر ولی <Set>
عناصر فرزند <FormParam>

عنصر <FormParams> از نحو زیر استفاده می‌کند:

نحوs79

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

مثال ۱s80

مثال زیر پارامتر فرمی به‌نام «myparam» را روی مقدار متغیر request.header.myparam در درخواست سفارشی جدیدی تنظیم می‌کند:

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

فقط زمانی می‌توانید از <FormParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ POST
  • نوع پیام: درخواست

اگر پارامترهای فرم خالی را در خط‌مشی‌تان تعریف کنید (<Add><FormParams/></Add>)، خط‌مشی هیچ پارامتر فرمی اضافه نمی‌کند. این کار مانند حذف کردن <FormParams> است.

‫<Set> قبل‌از ارسال پیام به نقطه پایانی هدف، Content-Type پیام را به «application/x-www-form-urlencoded» تغییر می‌دهد.

‫<Headers> (فرزند <Set>)

سرایندهای اچ‌تی‌تی‌پی موجود در درخواست یا پاسخ را رونویسی می‌کند، که توسط عنصر <AssignTo> مشخص می‌شود.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <Header> عنصر
عنصر ولی <Set>
عناصر فرزند <Header>

عنصر <Headers> از نحو زیر استفاده می‌کند:

نحوs81

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

مثال ۱s81

مثال زیر سرصفحه x-ratelimit-remaining را روی مقدار متغیر ratelimit.Quota-1.available.count تنظیم می‌کند:

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

اگر سرصفحه‌های خالی در خط‌مشی‌تان تعریف کنید (<Set><Headers/></Set>)، خط‌مشی هیچ سرصفحه‌ای تنظیم نمی‌کند. این کار همان تأثیر حذف <Headers> را خواهد داشت.

‫<Path> (فرزند <Set>)

‫<Payload> (فرزند <Set>)

بدنه پیام را برای درخواست یا پاسخ تعریف می‌کند که با عنصر <AssignTo> مشخص می‌شود. پایه‌بار می‌تواند هر نوع محتوای معتبری باشد، مانند نوشتار ساده، JSON، یا XML.

مقدار پیش‌فرض رشته خالی
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <Set>
عناصر فرزند هیچ‌کدام

عنصر <Payload> از نحو زیر استفاده می‌کند:

نحوs82

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

مثال ۱s83

مثال زیر بار داده نوشتار ساده را تنظیم می‌کند:

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

مثال ۲s84

مثال زیر پایه‌بار JSON را تنظیم می‌کند:

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

مثال ۳s85

مثال زیر مقادیر متغیر را با قرار دادن نام‌های متغیر در آکولاد، در پایه‌بار درج می‌کند:

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

در نسخه‌های قبلی Apigee، نمی‌توانستید از آکولاد برای نشان دادن ارجاع‌های متغیر در پایه‌بارهای JSON استفاده کنید. در آن نسخه‌ها، باید از مشخصه‌های variablePrefix و variableSuffix برای مشخص کردن نویسه‌های جداکننده استفاده می‌کردید و از آن‌ها برای پوشاندن نام‌های متغیر استفاده می‌کردید، مانند این:

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

این نحو قدیمی‌تر هنوز کار می‌کند.

مثال ۴s86

محتوای <Payload> به‌عنوان الگوی پیام درنظر گرفته می‌شود. یعنی خط‌مشی AssignMessage متغیرهای داخل آکولاد را با مقدار متغیرهای ارجاع‌شده در زمان اجرا جایگزین می‌کند.

مثال زیر از نحو آکولاد برای تنظیم بخشی از بار مفید روی مقدار متغیر استفاده می‌کند:

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

جدول زیر مشخصه‌های <Payload> را شرح می‌دهد:

مشخصه شرح حضور نوع
contentType

درصورت مشخص شدن، مقدار contentType به سرصفحه HTTP Content-Type اختصاص داده می‌شود.

اختیاری رشته
variablePrefix به‌طور اختیاری جداکننده ابتدایی را در متغیر جریان مشخص می‌کند. پیش‌فرض روی «{» است. برای اطلاعات بیشتر، به مرجع متغیرهای جریان مراجعه کنید. اختیاری Char
variableSuffix به‌طور اختیاری، حائل انتهایی را در متغیر جریان مشخص می‌کند. پیش‌فرض «}» است. برای اطلاعات بیشتر، مرجع متغیرهای جریان را ببینید. اختیاری Char

‫<QueryParams> (فرزند <Set>)

پارامترهای پُرسمان موجود در درخواست را با مقادیر جدید رونویسی می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن آرایه <QueryParam> عنصر
عنصر ولی <Set>
عناصر فرزند <QueryParam>

عنصر <QueryParams> از نحو زیر استفاده می‌کند:

نحوs87

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

مثال ۱s88

مثال زیر پارامتر پُرسمان «address» را روی مقدار متغیر request.header.address تنظیم می‌کند:

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

فقط زمانی می‌توانید از <QueryParams> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • فعل HTTP: ‏ GET
  • نوع پیام: درخواست

اگر پارامترهای پُرسمان خالی در خط‌مشی‌تان تعریف کنید (<Set><QueryParams/></Set>)، خط‌مشی هیچ پارامتر پُرسمانی تنظیم نمی‌کند. این کار مانند حذف <QueryParams> است.

‫<ReasonPhrase> (فرزند <Set>)

عبارت دلیل را در پاسخ تنظیم می‌کند. این کار معمولاً برای اشکال‌زدایی در ترکیب با <StatusCode> انجام می‌شود. این عنصر تأثیری بر درخواست ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته
عنصر ولی <Set>
عناصر فرزند هیچ‌کدام

عنصر <ReasonPhrase> از نحو زیر استفاده می‌کند:

نحوs89

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

مثال ۱s90

مثال زیر عبارت دلیل ساده‌ای را تعریف می‌کند:

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

مثال ۲s91

محتوای <ReasonPhrase> به‌عنوان الگوی پیام درنظر گرفته می‌شود. یعنی نام متغیری که در آکولاد قرار گرفته است در زمان اجرا با مقدار متغیر ارجاع‌شده جایگزین خواهد شد، همان‌طور که در مثال زیر نشان داده شده است:

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

فقط زمانی می‌توانید از <ReasonPhrase> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: پاسخ

‫<StatusCode> (فرزند <Set>)

کد وضعیت را در پاسخ تنظیم می‌کند. این عنصر تأثیری بر درخواست ندارد.

مقدار پیش‌فرض ‫«۲۰۰» (وقتی مشخصه createNew مربوط به <AssignTo> روی «true» تنظیم شده باشد)
الزامی است؟ اختیاری
تایپ کردن رشته یا variable
عنصر ولی <Set>
عناصر فرزند هیچ‌کدام

عنصر <StatusCode> از نحو زیر استفاده می‌کند:

نحوs92

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

مثال ۱

مثال زیر رمز وضعیت ساده‌ای را تنظیم می‌کند:

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

مثال ۲

محتوای <StatusCode> به‌عنوان الگوی پیام درنظر گرفته می‌شود. یعنی نام متغیری که در آکولاد قرار گرفته است در زمان اجرا با مقدار متغیر ارجاع‌شده جایگزین می‌شود، همان‌طور که در مثال زیر نشان داده شده است:

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

فقط زمانی می‌توانید از <StatusCode> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: پاسخ

‫<Verb> (فرزند <Set>)

فعل HTTP را در درخواست تنظیم می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته یا variable
عنصر ولی <Set>
عناصر فرزند هیچ‌کدام

عنصر <Verb> از نحو زیر استفاده می‌کند:

نحو

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

مثال ۱s93

مثال زیر یک فعل ساده را در درخواست تنظیم می‌کند:

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

مثال ۲s94

محتوای <Verb> به‌عنوان الگوی پیام درنظر گرفته می‌شود. این یعنی نام متغیر که در آکولاد قرار گرفته است در زمان اجرا با مقدار متغیر ارجاع‌شده جایگزین خواهد شد.

مثال زیر از متغیری برای پر کردن فعل استفاده می‌کند:

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

فقط زمانی می‌توانید از <Verb> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست

‫<Version> (فرزند <Set>)

نسخه HTTP را در درخواست تنظیم می‌کند. این عنصر تأثیری بر پاسخ ندارد.

مقدار پیش‌فرض نامربوط
الزامی است؟ اختیاری
تایپ کردن رشته یا variable
عنصر ولی <Set>
عناصر فرزند هیچ‌کدام

عنصر <Version> از نحو زیر استفاده می‌کند:

نحوs95

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

مثال ۱s96

مثال زیر شماره نسخه را روی «1.1» تنظیم می‌کند:

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

مثال ۲

در مثال زیر، از متغیری در آکولاد برای تنظیم شماره نسخه استفاده شده است:

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

محتوای <Version> به‌عنوان الگوی پیام درنظر گرفته می‌شود. یعنی نام متغیری که در آکولاد قرار گرفته است در زمان اجرا با مقدار متغیر ارجاع‌شده جایگزین خواهد شد.

فقط زمانی می‌توانید از <Version> استفاده کنید که معیارهای زیر برآورده شده باشد:

  • نوع پیام: درخواست

ایجاد پیام‌های درخواست سفارشی

می‌توانید از خط‌مشی AssignMessage برای ایجاد پیام درخواست سفارشی استفاده کنید. پس‌از ایجاد درخواست سفارشی، می‌توانید به روش‌های زیر از آن استفاده کنید:

  • دسترسی به متغیرهای آن در خط‌مشی‌های دیگر
  • آن را به سرویس خارجی منتقل کند

برای ایجاد پیام درخواست سفارشی، از عنصر <AssignTo> در خط‌مشی AssignMessage استفاده کنید. createNew را روی «true» تنظیم کنید و نام پیام جدید را در بدنه عنصر مشخص کنید، همان‌طور که در مثال زیر نشان داده شده است:

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

به‌طور پیش‌فرض، Edge هیچ کاری با پیام درخواست سفارشی انجام نمی‌دهد. پس‌از ایجاد آن، Edge با درخواست اصلی به جریان ادامه خواهد داد. برای استفاده از درخواست سفارشی، خط‌مشی‌ای مانند خط‌مشی ServiceCallout را به پراکسی خود اضافه کنید که بتواند درخواست سفارشی را به یک سرویس خارجی ارسال کند.

نمونه‌های زیر پیام‌های درخواست سفارشی ایجاد می‌کنند:

مثال ۱s97

مثال زیر یک شیء درخواست سفارشی با «اختصاص پیام» ایجاد می‌کند:

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

این مثال:

  • شیء پیام درخواست جدیدی به‌نام «MyCustomRequest» ایجاد می‌کند.
  • در MyCustomRequest، این خط‌مشی:
    • مقدار سرایند HTTP user-agent را از درخواست ورودی به پیام جدید کپی می‌کند. چون <Copy> از مرجع مطلق برای متغیر جریان user-agent استفاده می‌کند، نیازی به مشخص کردن مشخصه source برای <Copy> نیست.
    • پارامتر پُرسمان address را در پیام سفارشی روی مقدار پارامتر پُرسمان addy درخواست ورودی تنظیم می‌کند.
    • فعل HTTP را روی GET تنظیم می‌کند.
  • <IgnoreUnresolvedVariables> را روی «false» (نادرست) تنظیم می‌کند. وقتی <IgnoreUnresolvedVariables> «false» باشد، اگر یکی از متغیرهایی که خط‌مشی سعی می‌کند اضافه کند وجود نداشته باشد، Edge پردازش را در جریان میانای برنامه‌سازی کاربردی متوقف خواهد کرد.

مثال ۲s98

در اینجا مثال دیگری آورده شده است که نحوه ایجاد شیء درخواست سفارشی با Assign Message را نشان می‌دهد:

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

این نمونه درخواست سفارشی جدیدی به‌نام «partner.request» ایجاد می‌کند. سپس <Verb> و <Payload> را در درخواست جدید تنظیم می‌کند.

می‌توانید به پیام درخواست سفارشی در خط‌مشی AssignMessage دیگری که بعداً در جریان رخ می‌دهد دسترسی داشته باشید. مثال زیر مقدار سرصفحه user-agent پیام درخواست سفارشی را دریافت می‌کند:

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

ویدیوها

برای کسب اطلاعات بیشتر درباره خط‌مشی AssignMessage، ویدیوهای زیر را تماشا کنید.

ویدیو شرح
چرا خط‌مشی پیام اختصاص داده شود؟ با مزایای استفاده از خط‌مشی AssignMessage برای اصلاح درخواست یا پاسخ میانای برنامه‌سازی کاربردی بدون اصلاح کد پس‌بک آشنا شوید.
کپی کردن عناصر میانای برنامه‌سازی کاربردی بااستفاده از خط‌مشی AssignMessage عناصر را از درخواست یا پاسخ API کپی کنید و بااستفاده از خط‌مشی AssignMessage، شیء درخواست یا پاسخ جدیدی بسازید.
برداشتن عناصر میانای برنامه‌سازی کاربردی بااستفاده از خط‌مشی AssignMessage بااستفاده از خط‌مشی AssignMessage، عناصر میانای برنامه‌سازی کاربردی را بردارید و میانای برنامه‌سازی کاربردی را قبل‌از رسیدن به پسای هدف اصلاح کنید.
افزودن و تنظیم عناصر میانای برنامه‌سازی کاربردی بااستفاده از خط‌مشی AssignMessage درخواست یا پاسخ API را با افزودن پارامترهای پُرسمان، سرصفحه‌ها، پارامترهای فرم، یا بار مفید بااستفاده از خط‌مشی AssignMessage تغییر دهید.
ایجاد متغیرهای سفارشی بااستفاده از خط‌مشی AssignMessage متغیرهای جریان سفارشی را بااستفاده از خط‌مشی AssignMessage تنظیم کنید و از متغیرها در سایر خط‌مشی‌ها در پراکسی میانای برنامه‌سازی کاربردی استفاده کنید.
ایجاد اشیاء درخواست یا پاسخ جدید بااستفاده از خط‌مشی AssignMessage بااستفاده از خط‌مشی AssignMessage در زمان اجرای API، اشیای درخواست یا پاسخ API جدید ایجاد کنید.
ایجاد میانای برنامه‌سازی کاربردی ساختگی بااستفاده از خط‌مشی AssignMessage با افزودن خط‌مشی AssignMessage در جریان پاسخ، یک REST API ساختگی ساده ایجاد کنید.
تنظیم یا اصلاح بارداده بااستفاده از خط‌مشی AssignMessage تبدیل درخواست REST به درخواست SOAP با تنظیم بار داده SOAP بااستفاده از خط‌مشی AssignMessage در زمان اجرای API.

کدهای خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطایی را که Edge هنگام راه‌اندازی خطا در این خط‌مشی تنظیم می‌کند شرح می‌دهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه می‌دهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدو رسیدگی به اشکالات را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای خط‌مشی رخ دهند.

کد خطا وضعیت HTTP علت رفع اشکال
steps.assignmessage.SetVariableFailed ۵۰۰ خط‌مشی نتوانست متغیری را تنظیم کند. رشته خطا را برای نام متغیر حل‌نشده ببینید.
steps.assignmessage.VariableOfNonMsgType ۵۰۰

اگر مشخصه source در عنصر <Copy> روی متغیری تنظیم شده باشد که از نوع پیام نباشد، این خطا رخ می‌دهد.

متغیرهای نوع پیام نشان‌دهنده کل درخواست‌ها و پاسخ‌های HTTP هستند. متغیرهای جریان داخلی Edge request، response، و message از نوع پیام هستند. برای کسب اطلاعات بیشتر درباره متغیرهای پیام، مرجع متغیرها را ببینید.

steps.assignmessage.UnresolvedVariable ۵۰۰

این خطا زمانی رخ می‌دهد که متغیری که در خط‌مشی «اختصاص پیام» مشخص شده است یکی از این دو حالت را داشته باشد:

  • خارج از محدوده (در جریان خاصی که خط‌مشی در آن اجرا می‌شود دردسترس نیست)
  • یا
  • قابل‌حل نیست (تعریف نشده است)

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

نام خطا علت رفع اشکال
InvalidIndex اگر شاخص مشخص‌شده در عناصر <Copy> و/یا <Remove> خط‌مشی «تخصیص پیام» صفر یا عددی منفی باشد، استقرار «پراکسی API» ناموفق خواهد بود.
InvalidVariableName اگر عنصر فرزند <Name> خالی باشد یا در عنصر <AssignVariable> مشخص نشده باشد، استقرار پراکسی API ناموفق خواهد بود زیرا نام متغیر معتبری وجود ندارد که مقدار به آن اختصاص داده شود. نام متغیر معتبری لازم است.
InvalidPayload بار مشخص‌شده در خط‌مشی نامعتبر است.

متغیرهای خطا

این متغیرها زمانی تنظیم می‌شوند که این خط‌مشی در زمان اجرا باعث بروز خطا شود. برای اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانید را ببینید.

متغیر مکان مثال
fault.name="fault_name" ‫fault_name نام خطا است، همان‌طور که در جدول خطاهای زمان اجرا در بالا فهرست شده است. نام خطا آخرین بخش کد خطا است. fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed ‫policy_name نام مشخص‌شده کاربر برای خط‌مشی‌ای است که خطا را ایجاد کرده است. assignmessage.AM-SetResponse.failed = true

نمونه پاسخ خطا

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

قانون خطای نمونه

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

طرح‌واره‌ها

هر نوع خط‌مشی با یک طرح‌واره XML (.xsd) تعریف می‌شود. برای مرجع، طرح‌واره‌های خط‌مشی در GitHub دردسترس هستند.

موضوعات مرتبط

نمونه‌های فعال خط‌مشی AssignMessage در نمونه‌های پلاتفرم API دردسترس است.

برای مثال پیشرفته‌تری از نحوه لغو target.url از ProxyEndpoint، این مقاله «انجمن Apigee» را ببینید.

برای دیدن «تنظیم مسیر» در عمل در خط‌مشی ServiceCallout، این نمونه یادگیری با انجام دادن را در نمونه‌های Apigee GitHub بررسی کنید. کافی است مخزن را شبیه‌سازی کنید و دستورالعمل‌های آن موضوع را دنبال کنید. این مثال از خط‌مشی AssignMessage برای تنظیم مسیر درخواست استفاده می‌کند، سپس از خط‌مشی Service Callout برای ارسال درخواست به سرویس خارجی استفاده می‌کند.