سياسة تخصيص الرسائل

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستند Apigee X.
المعلومات

الموضوع

تتغير سياسة AssignMessage أو تنشئ رسائل جديدة لطلبات الردّ والطلبات أثناء مسار الخادم الوكيل لواجهة برمجة التطبيقات. تسمح لك السياسة بتنفيذ الإجراءات التالية على هذه الرسائل:

  • إضافة مَعلمات نماذج أو رؤوس أو مَعلمات طلب بحث جديدة إلى رسالة
  • نسخ المواقع الإلكترونية الحالية من رسالة إلى أخرى
  • إزالة الرؤوس و/أو مَعلمات طلب البحث و/أو مَعلمات النماذج و/أو حمولات الرسائل من رسالة
  • تحديد قيمة الخصائص الحالية في رسالة

في حال استخدام سياسة AssignMessage، يمكنك عادةً إضافة خصائص للطلب أو الردّ أو تغييرها أو إزالتها. مع ذلك، يمكنك أيضًا استخدام سياسة AssignMessage لإنشاء طلب مخصّص أو رسالة استجابة مخصّصة وتمريرها إلى هدف بديل، كما هو موضّح في إنشاء رسائل طلب مخصّصة.

يمكن لسياسة AssignMessage إنشاء متغيّرات التدفق أو تغييرها باستخدام العناصر الثانوية التالية:

عنصر <AssignMessage>

تحدِّد هذه السياسة سياسة AssignMessage.

القيمة التلقائية راجِع علامة التبويب السياسة التلقائية أدناه.
هل هي مطلوبة؟ مطلوبة
النوع عنصر معقد
العنصر الرئيسي timing fixed in amara
العناصر الثانوية <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

يستخدم العنصر <AssignMessage> البنية التالية:

البنية

يستخدم العنصر <AssignMessage> البنية التالية:

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

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

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

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

  <DisplayName>policy_display_name</DisplayName>

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

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

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

</AssignMessage>

السياسة التلقائية

يوضح المثال التالي الإعدادات التلقائية عند إضافة سياسة AssignMessage إلى مسارك في واجهة مستخدم Edge:

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

عند إدراج سياسة AssignMessage جديدة في واجهة مستخدم Edge، يحتوي النموذج على رموز كعبية لجميع العمليات الممكنة. ويتم عادةً اختيار العمليات المطلوب تنفيذها باستخدام هذه السياسة وإزالة بقية العناصر الفرعية. على سبيل المثال، إذا كنت تريد إجراء عملية نسخ، استخدِم العنصر <Copy> وأزِل <Add> و<Remove> والعناصر الفرعية الأخرى من السياسة لتسهيل قراءتها.

يتضمن هذا العنصر السمات التالية الشائعة لجميع السياسات:

السمة تلقائي مطلوب الوصف
name لا ينطبق مطلوب

الاسم الداخلي للسياسة. يمكن أن تحتوي قيمة السمة name على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. ويجب ألا تتجاوز هذه القيمة 255 حرفًا.

اختياريًا، يمكنك استخدام العنصر <DisplayName> لتصنيف السياسة في محرّر الخادم الوكيل لواجهة مستخدم الإدارة باستخدام اسم بلغة مختلفة.

continueOnError false إجراء اختياري يمكنك ضبطها على "خطأ" لعرض رسالة خطأ عند تعذّر تنفيذ إحدى السياسات. ويُعدّ هذا سلوكًا متوقعًا في معظم السياسات. يمكنك ضبط القيمة على "صحيح" للاستمرار في تنفيذ العملية حتى بعد تعذُّر تنفيذ سياسة.
enabled صحيح إجراء اختياري اضبط القيمة على "true" لفرض السياسة. اضبط هذه القيمة على "false" على "إيقاف" السياسة. لن يتم فرض السياسة حتى إذا ظلت مرتبطة بتدفق.
async   false منهي العمل به تم إيقاف هذه السمة نهائيًا.

يقدّم الجدول التالي وصفًا عالي المستوى للعناصر الثانوية في <AssignMessage>:

عنصر فرعي مطلوب؟ الوصف
العمليات الشائعة
<Add> اختياري تضيف معلومات إلى كائن الرسالة الذي يحدّده العنصر <AssignTo>.

يضيف <Add> عناوين أو معلَمات إلى الرسالة غير الموجودة في الرسالة الأصلية. لاستبدال الرؤوس أو المَعلمات الحالية، استخدِم العنصر <Set>.

<Copy> اختياري يتم نسخ المعلومات من الرسالة التي تحدّدها السمة source إلى كائن الرسالة الذي يحدّده العنصر <AssignTo>.
<Remove> اختياري يؤدي إلى حذف العناصر المحدّدة من متغيّر الرسالة المحدّد في عنصر <AssignTo>.
<Set> اختياري تستبدِل قيم السمات الحالية في الطلب أو الاستجابة، والتي يتم تحديدها من خلال العنصر <AssignTo>.

يستبدل <Set> العناوين أو المَعلمات التي سبق أن تم توفيرها في الرسالة الأصلية. لإضافة رؤوس أو مَعلمات جديدة، استخدِم العنصر <Add>.

العناصر الفرعية الأخرى
<AssignTo> اختياري تحدِّد هذه السياسة الرسالة التي تعمل عليها سياسة AssignMessage. وقد تكون هذه الطريقة هي الطلب أو الردّ العادي، أو رسالة مخصّصة جديدة.
<AssignVariable> اختياري يعيّن قيمة لمتغيّر تدفق. في حال عدم توفّر المتغيّر، سيُنشئه <AssignVariable>.
<IgnoreUnresolvedVariables> اختياري لتحديد ما إذا كانت المعالجة تتوقف عند مصادفة متغير لم يتم حله.

ويتم وصف كل عنصر من هذه العناصر الفرعية في الأقسام التالية.

أمثلة

توضِّح الأمثلة التالية بعض الطرق التي يمكنك من خلالها استخدام سياسة AssignMessage:

1: إضافة عنوان

يضيف المثال التالي عنوانًا إلى الطلب باستخدام العنصر <Add>:

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

2: إزالة الحمولة

يؤدي المثال التالي إلى حذف الحمولة من الاستجابة التي تتضمن العنصر <Remove>:

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

3: تعديل الردّ

يعدِّل المثال التالي كائن استجابة حالي عن طريق إضافة عنوان إليه:

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

لا يؤدي هذا المثال إلى إنشاء رسالة جديدة. بدلاً من ذلك، يعدّل رسالة استجابة حالية عن طريق إضافة عنوان HTTP.

تعدّل هذه السياسة كائن الاستجابة الذي يعرضه الخادم الهدف لأنّ هذا المثال لا يتضمّن اسم متغيّر في العنصر <AssignTo> ويحدّد type على أنّه "Response".

يتم اشتقاق عنوان HTTP الذي تمت إضافته إلى رسالة الاستجابة من خلال هذه السياسة من متغيّر تمت تعبئته عن طريق سياسة LookupCache. ولذلك، تحتوي رسالة الاستجابة التي تم تعديلها من خلال سياسة "تعيين الرسالة" هذه على عنوان HTTP يشير إلى ما إذا كان قد تم سحب النتائج من ذاكرة التخزين المؤقت أم لا. يمكن أن يكون تعيين العناوين في الاستجابة مفيدًا لتصحيح الأخطاء واستكشاف الأخطاء وإصلاحها.

4: ضبط المحتوى الديناميكي

يمكنك استخدام "تعيين رسالة" لتضمين المحتوى الديناميكي في حمولة الرسائل ورسائل الطلب.

لتضمين متغيّرات تدفق Edge في حمولة XML، عليك لف المتغيّر المعيّن بين أقواس معقوفة، على النحو التالي: {prefix.name}.

يضمِّن المثال التالي قيمة متغيّر مسار عنوان HTTP user-agent في عنصر XML يُسمى User-agent:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

بالنسبة إلى حمولات JSON، يمكنك إدراج المتغيّرات باستخدام السمتَين variablePrefix وvariableSuffix مع المحدِّدات كما هو موضّح في المثال التالي:

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

للحصول على قائمة كاملة بمتغيرات التدفق، يُرجى الاطّلاع على مرجع متغيرات التدفق.

بدءًا من إصدار السحابة الإلكترونية 16.08.17، يمكنك أيضًا استخدام الأقواس المعقوفة لإدراج المتغيرات.

5: إزالة معلمة طلب البحث

يزيل المثال التالي مَعلمة طلب البحث apikey من الطلب:

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

ومن بين أفضل الممارسات إزالة مَعلمة طلب البحث apikey من رسالة الطلب عند استخدام سياسة CheckAPIKey لمصادقة المستخدم. يمكنك القيام بذلك لمنع تمرير معلومات المفتاح الحساسة إلى الهدف الخلفي.

6: ضبط/الحصول على المتغيّرات

يستخدم المثال التالي ثلاث سياسات "تعيين للرسالة":

  1. تنشئ ثلاثة متغيرات تدفق في الطلب، بقيم ثابتة
  2. الحصول على متغيّرات التدفق ديناميكيًا في سياسة ثانية في مسار الطلب
  3. تضعها في حمولة الاستجابة
<!-- Policy #1: Set variables in the request -->
<AssignMessage continueOnError="false" enabled="true" name="set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

في السياسة الأولى، يُنشئ العنصر <AssignVariable> ويضبط ثلاثة متغيرات في الطلب. يحدد كل عنصر <Name> اسم متغيّر، وتحدّد <Value> القيمة.

تستخدم السياسة الثانية العنصر <AssignVariable> لقراءة القيم وتنشئ ثلاثة متغيّرات جديدة:

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

في السياسة الثانية، يشير العنصر <Ref> إلى المتغيّر المصدر، وتحدّد عناصر <Name> أسماء المتغيّرات الجديدة. إذا تعذّر الوصول إلى المتغيّر المشار إليه من العنصر <Ref>، يمكنك استخدام القيمة التي حدّدها العنصر <Value>.

لتجربة هذه المجموعة من السياسات:

  1. أضِف السياستين 1 و2 إلى تدفق الطلب. احرص على وضع السياسة رقم 1 قبل السياسة رقم 2.
  2. أضِف السياسة الثالثة في مسار الرد.
  3. تستخدم السياسة الثالثة العنصر <Set> لإضافة المتغيّرات إلى الاستجابة. ينشئ المثال التالي حمولة 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>

7: الحصول على عناوين استجابة وسيلة شرح الخدمة

في المثال التالي، لنفترض أنّ سياسة ServiceCallout متضمّنة في طلب الخادم الوكيل لواجهة برمجة التطبيقات، وتحتوي استجابة وسيلة الشرح على عدة عناوين تحمل الاسم نفسه (Set-Cookie). على افتراض أنّ متغيّر استجابة وسيلة شرح الخدمة هو القيمة التلقائية calloutResponse، تحصل السياسة التالية على قيمة رأس Set-Cookie الثانية.

<AssignMessage continueOnError="false" enabled="true" name="get-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

لإدراج جميع قيم العناوين، استخدِم المتغيّر التالي بدلاً من ذلك:

{calloutResponse.header.Set-Cookie.values}

لكل عنصر فرعي في هذا المرجع أمثلة إضافية. للاطّلاع على مزيد من الأمثلة، يمكنك الاطّلاع على مثال على AssignMessage على GitHub.

مرجع عنصر فرعي

يصف هذا القسم العناصر الفرعية لـ <AssignMessage>.

<Add>

يضيف معلومات إلى الطلب أو الردّ الذي يحدّده العنصر <AssignTo>.

يضيف العنصر <Add> سمات جديدة إلى الرسالة غير المتوفّرة في الرسالة الأصلية. لتغيير قيم السمات الحالية، استخدِم العنصر <Set>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع نوع معقد
العنصر الرئيسي <AssignMessage>
العناصر الثانوية <FormParams>
<Headers>
<QueryParams>

يستخدم العنصر <Add> البنية التالية:

البنية

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

مثال 1

يستخدم المثال التالي العنصر <FormParams> للحصول على قيم ثلاث معلَمات سلسلة طلب البحث من الطلب الأولي وضبطها كمَعلمات نموذج في طلب نقطة النهاية الهدف:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

مثال 2

يستخدم المثال التالي العنصر <Headers> لإضافة عنوان User-Agent إلى طلب نقطة النهاية الهدف:

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

مثال 3

يستخدم المثال التالي العنصر <QueryParams> لإضافة معلَمة طلب بحث واحدة ذات قيمة ثابتة إلى الطلب:

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

يستخدم هذا المثال السمة <Add> في التدفق المسبق للطلب. عند النظر إلى النتائج في أداة، مثل أداة التتبُّع، سيصبح الطلب "http://httpbin.org/get" هو "http://httpbin.org/get?myParam=42".

تتيح العناصر الثانوية في <Add> إمكانية استبدال السلسلة الديناميكية، والمعروفة باسم نموذج الرسالة.

<FormParams> (تابع <Add>)

إضافة مَعلمات نموذج جديدة إلى رسالة الطلب ولا يؤثر هذا العنصر في رسالة الردّ.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <FormParam>
العنصر الرئيسي <Add>
العناصر الثانوية <FormParam>

يستخدم العنصر <FormParams> البنية التالية:

البنية

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

مثال 1

يضيف المثال التالي مَعلمة نموذج واحد ("answer") وقيمة ثابتة ("42") إلى الطلب:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"></AssignTo>
</AssignMessage>

مثال 2

يحصل المثال التالي على قيمة معلَمة سلسلة طلب البحث name ويضيفها إلى الطلب كمعلّمة نموذج:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
</AssignMessage>

يُرجى العِلم أنّ هذا المثال لا يحدّد هدفًا باستخدام <AssignTo>. تضيف هذه السياسة المَعلمة إلى الطلب فقط.

مثال 3

يضيف المثال التالي مَعلمات نموذج متعددة إلى الطلب:

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

يحصل هذا المثال على معلَمات سلسلة طلب البحث من الطلب الأصلي ويضيفها كمَعلمات نموذج إلى الطلب المُرسَل إلى نقطة النهاية المستهدفة.

يمكنك استخدام أداة التتبُّع للاطّلاع على التدفق. سيظهر لك أنّ نص الطلب يحتوي على بيانات النموذج بترميز عنوان URL، والتي تم تمريرها في الأصل كمعلَمات سلسلة طلب بحث:

%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en

لا يمكنك استخدام <FormParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: POST
  • نوع الرسالة: طلب
  • أحد الخيارات التالية (أو كليهما):
    • بيانات النموذج: يجب ضبطها على قيمة معيّنة أو "" (السلسلة الفارغة). على سبيل المثال، باستخدام curl، يمكنك إضافة -d "" إلى طلبك.
    • عنوان Content-Length: يتم ضبط القيمة على 0 (إذا لم تتوفّر أي بيانات في الطلب الأصلي، أو الطول الحالي بالبايت). على سبيل المثال، باستخدام curl، أضِف -H "Content-Length: 0" إلى طلبك.

مثال:

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

عند إضافة <FormParams>، يضبط Edge عنوان Content-Type للطلب على "APPLICATION/x-www-form-urlEncrypt" قبل إرسال الرسالة إلى الخدمة المستهدَفة.

<Headers> (تابع <Add>)

يضيف عناوين جديدة إلى الطلب أو الاستجابة المحدّدة التي يحدّدها العنصر <AssignTo>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <Header>
العنصر الرئيسي <Add>
العناصر الثانوية <Header>

يستخدم العنصر <Headers> البنية التالية:

البنية

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

مثال 1

يضيف المثال التالي عنوان user-agent إلى رسالة الطلب، ويحدّد قيمة متغيّر مسار request.user.agent لذلك العنوان.

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<QueryParams> (تابع <Add>)

تضيف مَعلمات طلب بحث جديدة إلى الطلب. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <QueryParam>
العنصر الرئيسي <Add>
العناصر الثانوية <QueryParam>

يستخدم العنصر <QueryParams> البنية التالية:

البنية

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

مثال 1

يضيف المثال التالي مَعلمة طلب البحث "myParam" إلى الطلب ويحدّد القيمة "42" له:

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

لا يمكنك استخدام <QueryParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: GET
  • نوع الرسالة: طلب

بالإضافة إلى ذلك، لا يمكنك ضبط معلَمات طلب البحث إلا عندما تكون السمة type للعنصر <AssignTo> رسالة طلب. وليس لذلك أي تأثير في حال ضبطها على الاستجابة.

إذا حدّدت مصفوفة فارغة من معلَمات طلب البحث في سياستك (<Add><QueryParams/></Add>)، لا تضيف السياسة أي معلَمات طلب بحث. وينطبق ذلك تمامًا على حذف <QueryParams>.

<AssignTo>

تحدِّد هذه السياسة العنصر الذي تعمل عليه سياسة AssignMessage. تشمل الخيارات ما يلي:

  • رسالة الطلب: request التي يتلقاها الخادم الوكيل لواجهة برمجة التطبيقات
  • رسالة الاستجابة: يتم عرض response من الخادم الهدف.
  • رسالة مخصّصة: طلب مخصّص أو عنصر ردّ

يُرجى العلم أنّه في بعض الحالات، لا يمكنك تغيير العنصر الذي تعمل عليه سياسة AssignMessage. على سبيل المثال، لا يمكنك استخدام <Add> أو <Set> لإضافة أو تغيير مَعلمات طلب البحث (<QueryParams>) أو مَعلمات النموذج (<FormParams>) في الردّ. يمكنك فقط معالجة معلَمات طلب البحث ومعلَمات النموذج في الطلب.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <AssignMessage>
العناصر الثانوية لا ينطبق

إذا لم تحدّد <AssignTo>، تسري السياسة على الطلب أو الاستجابة التلقائية التي تستند إلى مكان تنفيذ السياسة. في حال تنفيذ السياسة في مسار الطلب، ستؤثِّر في رسالة الطلب. وفي حال تنفيذها في مسار الاستجابة، تؤثر السياسة في الاستجابة تلقائيًا.

يستخدم العنصر <AssignTo> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي أنّ الهدف هو الطلب الأصلي الذي سيتم إرساله إلى نقطة النهاية المستهدفة:

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

من خلال ضبط createNew على "خطأ" (الخيار التلقائي)، لا يؤدي هذا المثال إلى إنشاء طلب جديد. تؤثر جميع العمليات في هذه السياسة في الطلب الأصلي.

مثال 2

ينشئ المثال التالي كائن طلب جديدًا:

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

عند إنشاء طلب جديد أو عنصر استجابة جديد، تعتمد العناصر الأخرى في سياسة AssignMessage (مثل <Add> و<Set> و<Set>) على عنصر الطلب الجديد هذا.

يمكنك الوصول إلى عنصر الطلب الجديد في سياسات أخرى لاحقًا خلال المسار، أو إرسال كائن الطلب الجديد إلى خدمة خارجية باستخدام سياسة ServiceCallout.

مثال 3

ينشئ المثال التالي كائن طلب جديدًا باسم "MyRequestObject":

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

عند إنشاء طلب جديد أو عنصر استجابة جديد، تعتمد العناصر الأخرى في سياسة AssignMessage (مثل <Add> و<Set> و<Set>) على عنصر الطلب الجديد هذا.

يمكنك الوصول إلى عنصر الطلب الجديد في سياسات أخرى لاحقًا خلال المسار، أو إرسال كائن الطلب الجديد إلى خدمة خارجية باستخدام سياسة ServiceCallout.

يوضِّح الجدول التالي سمات <AssignTo>:

السمة الوصف مطلوب؟ النوع
createNew

تحدِّد هذه السياسة ما إذا كانت هذه السياسة ستنشئ رسالة جديدة عند تحديد القيم.

إذا كانت القيمة "true"، ستنشئ السياسة متغيّرًا جديدًا من النوع الذي تحدّده السمة type (إما "الطلب" أو "الاستجابة"). إذا لم تحدّد اسم المتغيّر الجديد، ستنشئ السياسة طلب أو عنصر استجابة جديدًا استنادًا إلى قيمة type.

إذا كانت القيمة "خطأ"، ستستجيب السياسة بإحدى الطريقتَين التاليتَين:

  • إذا كان بإمكان <AssignTo> تحويل اسم المتغيّر إلى طلب أو ردّ، ستتم مواصلة المعالجة. على سبيل المثال، إذا كانت السياسة في مسار الطلب، يكون المتغيّر هو كائن الطلب. إذا كانت السياسة في إحدى الردود، يكون المتغيّر هو كائن الاستجابة.
  • إذا تعذَّر حلّ <AssignTo>، أو إذا تم حلها إلى نوع غير الرسائل، تعرض السياسة خطأ.

إذا لم يتم تحديد createNew، تستجيب السياسة بإحدى الطريقتين التاليتين:

  • إذا تم تحويل <AssignTo> إلى رسالة، يتم نقل المعالجة إلى الخطوة التالية.
  • إذا تعذّر حل السمة <AssignTo> أو تم تحويلها إلى نوع غير الرسائل، يتم إنشاء متغيّر جديد من النوع المحدّد في type.
اختياري منطقي
transport

تُحدِّد نوع النقل لنوع الطلب أو رسالة الرد.

القيمة التلقائية هي "http" (القيمة الوحيدة المتوافقة).

اختياري سلسلة
type تُحدِّد هذه السياسة نوع الرسالة الجديدة عندما تكون قيمة createNew هي "true". والقيم الصالحة هي "request" أو "response".

القيمة التلقائية هي "request". إذا لم تستخدم هذه السمة، سينشئ Edge إما طلبًا أو استجابة بناءً على المكان الذي يتم تنفيذ هذه السياسة فيه.

اختياري سلسلة

<AssignVariable>

تحدّد قيمة لمتغيّر مسار الوجهة (مثل متغيّر يتم ضبط قيمته من خلال سياسة AssignMessage). في حال عدم توفّر متغيّر التدفق، سيتم إنشاؤه من خلال <AssignVariable>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع نوع معقد
العنصر الرئيسي <AssignMessage>
العناصر الثانوية <Name> (مطلوبة)
<Ref>
<Template>
<Value>

يمكن أن تكون القيمة التي تعينها لمتغير تدفق الوجهة واحدة مما يلي:

  • السلسلة الحرفية: استخدِم العنصر الفرعي <Value> لتحديد قيمة سلسلة حرفية لمتغيّر مسار الوجهة.
  • متغيّر التدفق: استخدِم العنصر الفرعي <Ref> لتحديد قيمة متغيّر التدفق الحالي لمتغيّر مسار الوجهة. للحصول على قائمة كاملة بمتغيّرات التدفق التي يمكن استخدامها كمصدر، يُرجى الاطّلاع على مرجع متغيّرات التدفق.
  • نموذج الرسالة: استخدِم العنصر الفرعي <Template> لتحديد نموذج رسالة لمتغيّر مسار الوجهة.

يستخدم العنصر <AssignVariable> البنية التالية:

البنية

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

استخدِم العنصر <Ref> لتحديد المتغيّر المصدر. إذا تعذّر الوصول إلى المتغيّر المُشار إليه من خلال <Ref>، سيستخدم Edge القيمة التي حدّدها العنصر <Value>. في حال تحديد السمة <Template>، تحظى بالأولوية على العناصر الفرعية الأخرى.

مثال 1

يحدّد المثال التالي قيمة المتغيّر الجديد، وهو myvar، على القيمة الحرفية "42":

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

مثال 2

يعيّن المثال التالي قيمة متغيّر التدفق request.header.user-agent إلى متغيّر مسار الوجهة myvar وقيمة مَعلمة طلب البحث country إلى متغيّر مسار الوجهة Country:

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

إذا تعذّر إجراء أي من عمليتَي التعيين، يخصّص Edge بدلاً من ذلك القيمة "ErrorOnCopy" لمتغير تدفق الوجهة.

في حال عدم توفّر متغيّرَي التدفق myvar أو Country، سيتم إنشاؤهما من خلال <AssignVariable>.

مثال 3

يستخدم المثال التالي العنصر الفرعي <Template> لربط متغيّرَي السياق باستخدام سلسلة حرفية (واصلة) بينهما:

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

من الاستخدامات الشائعة للسمة <AssignVariable> ضبط قيمة تلقائية لمَعلمة طلب بحث أو عنوان أو قيمة أخرى يمكن تمريرها مع الطلب. ويمكنك إجراء ذلك من خلال مزيج من العنصرَين الفرعيَين <Ref> و<Value>. لمزيد من المعلومات، اطّلِع على أمثلة <Ref>.

<Name> (تابع <AssignVariable>)

تُحدِّد اسم متغيّر مسار الوجهة (مثل المتغيّر الذي يتم ضبط قيمته من خلال سياسة AssignMessage). إذا لم يكن متغيّر الاسم في <AssignVariable> غير متوفّر، تنشئ السياسة متغيّرًا بهذا الاسم.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ مطلوبة
النوع سلسلة
العنصر الرئيسي <AssignVariable>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Name> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي متغيّر الوجهة على أنّه myvar، ويضبطه على القيمة الحرفية "42":

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

إذا لم تكن السمة myvar موجودة، سيقوم <AssignVariable> بإنشائها.

<Ref> (تابع <AssignVariable>)

تُحدِّد مصدر التعيين كمتغيّر تدفق. ويمكن أن يكون متغيّر التدفق أحد متغيّرات التدفق المحدّدة مسبقًا (كما هو موضّح في مرجع متغيّرات التدفق) أو متغيّر التدفق المخصّص الذي أنشأته.

يتم دائمًا تفسير قيمة <Ref> على أنّها متغيّر تدفق، ولا يمكنك تحديد سلسلة حرفية باعتبارها القيمة. ولتحديد قيمة سلسلة حرفية، استخدِم العنصر <Value> بدلاً من ذلك.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <AssignVariable>
العناصر الثانوية لا ينطبق

عند تحديد متغيّر تدفق باستخدام <Ref>، احذف الأقواس المضمّنة "{}" التي تستخدمها عادةً للإشارة إلى متغيّر التدفق. على سبيل المثال، لضبط قيمة المتغيّر الجديد على قيمة متغيّر التدفق client.host:

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

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

لتحديد قيمة تلقائية لمتغيّر مسار الوجهة، استخدِم <Value> مع <Ref>. إذا كان متغيّر التدفق المحدَّد في السمة <Ref> غير متوفّر أو لا يمكن قراءته أو كان لا قيمة، سيحدّد Edge قيمة <Value> لمتغيّر مسار الوجهة بدلاً من ذلك.

يستخدم العنصر <Ref> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي قيمة متغير التدفق request.header.user-agent إلى متغير مسار الوجهة myvar وقيمة مَعلمة طلب البحث country إلى المتغيّر Country:

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

في هذا المثال، لا يتم تحديد قيمة تلقائية (أو قيمة احتياطية) لخدمة Edge.

مثال 2

يعيّن المثال التالي قيمة متغير التدفق request.header.user-agent إلى متغير التدفق الوجهة myvar وقيمة معلمة طلب البحث country إلى المتغير Country:

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

في هذا المثال، إذا كانت قيم متغيّر التدفق request.header.user-agent أو مَعلمة طلب البحث Country فارغة أو غير قابلة للقراءة أو مكتوبة بشكلٍ غير صحيح، سيخصّص Edge القيمة "ErrorOnCopy" للمتغيّرات الجديدة.

مثال 3

من بين حالات الاستخدام الشائعة للسمة <AssignVariable> ضبط القيمة التلقائية لمعلَمة طلب البحث أو العنوان أو أي قيمة أخرى يمكن تمريرها مع الطلب. على سبيل المثال، يمكنك إنشاء خادم وكيل لواجهة برمجة تطبيقات الطقس حيث يأخذ الطلب معلَمة طلب بحث واحدة باسم "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 ويخصِّصها إلى نفسه. وإذا كان متغيّر التدفق فارغًا، ما يعني حذف معلَمة طلب البحث "w" من الطلب، يستخدم هذا المثال القيمة التلقائية من العنصر <Value>. وبالتالي، يمكنك إرسال طلب إلى الخادم الوكيل لواجهة برمجة التطبيقات هذا الذي يحذف مَعلمة طلب البحث "w":

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

...ولا يزال الخادم الوكيل لواجهة برمجة التطبيقات يعرض نتيجة صالحة.

على عكس استخدام <Value>، يجب أن تكون قيمة <Ref> أحد متغيّرات التدفق، مثل سمة الكائن request أو response أو target. يمكن أن تكون القيمة أيضًا متغيّر تدفقًا مخصّصًا أنشأته.

إذا حددت متغيّر تدفق غير متوفّر لقيمة <Ref>، وكانت قيمة <IgnoreUnresolvedVariables> هي "true"، تعرض Edge خطأ.

<Template> (تابع <AssignVariable>)

تحدِّد نموذج رسالة. يسمح لك نموذج الرسالة بإجراء استبدال سلسلة متغيرة عند تنفيذ السياسة، كما يمكنه دمج سلاسل حرفية مع أسماء متغيرات ملفوفة بأقواس معقوفة. بالإضافة إلى ذلك، تتوافق نماذج الرسائل مع وظائف مثل الخروج وتحويل الطلبات.

استخدِم السمة ref لتحديد متغيّر للتدفق حيث تكون قيمته عبارة عن نموذج رسالة. على سبيل المثال، يمكنك تخزين نموذج رسالة على أنّه سمة مخصّصة في أحد تطبيقات المطوّرين. عندما يتعرّف Edge على تطبيق المطوّر بعد أن يتحقّق من مفتاح واجهة برمجة التطبيقات أو الرمز المميّز للأمان (من خلال سياسة إضافية)، يمكن للعنصر <AssignVariable> استخدام نموذج الرسالة من السمة المخصّصة للتطبيق، وتتوفر كمتغيّر تدفق من سياسة الأمان. ويفترض المثال التالي أنّ نموذج الرسالة متوفّر في سمة العميل التي تحمل الاسم message_template على تطبيق المطوّر الذي يُجري طلب البيانات من واجهة برمجة التطبيقات، حيث تم استخدام سياسة CheckAPIKey للتحقّق من مفتاح واجهة برمجة التطبيقات الخاص بالتطبيق:

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

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <AssignVariable>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Template> البنية التالية:

البنية

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

مثال 1

يستخدم المثال التالي بنية نماذج الرسائل لإجراء تسلسل لمتغيّرَي سياق باستخدام سلسلة حرفية (واصلة) بينهما:

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

مثال 2

يحدّد المثال التالي متغيّر التدفق، حيث تكون قيمة المتغيّر عبارة عن نموذج رسالة محدد مسبقًا. استخدِم هذا الخيار إذا كنت تريد إدخال نموذج محدّد مسبقًا في وقت التشغيل بدون الحاجة إلى تعديل السياسة:

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

  </AssignVariable>
</AssignMessage>

مثال 3

يحدد المثال التالي متغير التدفق وقيمة نصية. في هذه الحالة، إذا لم يكن المتغيّر المُشار إليه فارغًا، سيتم استخدام هذه القيمة كنموذج. إذا كانت القيمة المشار إليها فارغة، سيتم استخدام القيمة النصية (في هذه الحالة، {system.uuid}-{messageid}) كنموذج. يكون هذا النمط مفيدًا في تقديم قيمة "تجاوز"، حيث تريد في بعض الحالات إلغاء النموذج التلقائي (جزء النص) باستخدام القيم التي يتم ضبطها ديناميكيًا. على سبيل المثال، يمكن أن تحصل العبارة الشرطية على قيمة من خريطة المفتاح/القيمة وتضبط المتغيّر المشار إليه على هذه القيمة:

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

<Value> (تابع <AssignVariable>)

تُحدِّد قيمة متغيّر مسار الوجهة الذي تم ضبطه باستخدام <AssignVariable>. يتم دائمًا تفسير القيمة على أنّها سلسلة حرفية، ولا يمكنك استخدام متغيّر التدفق كقيمة حتى إذا وضعت القيمة بين قوسَين ("{}"). ولاستخدام متغيّر تدفق، استخدِم <Ref> بدلاً من ذلك.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <AssignVariable>
العناصر الثانوية لا ينطبق

عند استخدام <Value> مع العنصر <Ref>، تكون القيمة التلقائية (أو الاحتياطية). وإذا لم يتم تحديد السمة <Ref> أو كانت غير قابلة للحلّ أو إذا كانت فارغة، يتم استخدام قيمة <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>، تنسخ هذه السياسة القيم إلى الطلب أو الاستجابة، بناءً على المكان الذي يتم فيه تنفيذ هذه السياسة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <AssignMessage>
العناصر الثانوية <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

يستخدم العنصر <Copy> البنية التالية:

البنية

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

مثال 1

في المثال التالي، يتم نسخ العنوان وثلاث مَعلمات للنموذج والمسار وجميع معلَمات طلب البحث من الطلب إلى طلب مخصّص جديد:

<AssignMessage continueOnError="false" enabled="true" name="copy-1">
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1">Header value 1</Header>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_2">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_3">Form param value 1</FormParam>
    </FormParams>
    <Payload>false</Payload>
    <Path>true</Path>
    <QueryParams/>
    <ReasonPhrase>false</ReasonPhrase>
    <StatusCode>false</StatusCode>
    <Verb>false</Verb>
    <Version>false</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

يحتوي العنصر <Copy> على السمات التالية:

السمة الوصف مطلوب؟ النوع
source

لتحديد العنصر المصدر للنسخة.

  • إذا لم يتم تحديد السمة source، يتم التعامل معها على أنّها رسالة بسيطة. على سبيل المثال، إذا كانت السياسة في مسار الطلب، سيتم ضبط المصدر تلقائيًا على العنصر request. إذا كانت السياسة متوفّرة في مسار الاستجابة، يتم ضبط السمة التلقائية على الكائن response. إذا حذفت source، يمكنك استخدام مرجع مطلق إلى متغيّر تدفق كمصدر للنسخة. على سبيل المثال، حدِّد القيمة على أنّها {request.header.user-agent}.
  • إذا تعذَّر حل متغير المصدر أو تم حله إلى نوع غير رسائل، لن يستجيب <Copy>.
اختياري سلسلة

<FormParams> (تابع <Copy>)

يتم نسخ مَعلمات النموذج من الطلب المحدَّد في السمة source الخاصة بالعنصر <Copy> إلى الطلب المحدّد من خلال العنصر <AssignTo>. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <FormParam> أو مصفوفة فارغة
العنصر الرئيسي <Copy>
العناصر الثانوية <FormParam>

يستخدم العنصر <FormParams> البنية التالية:

البنية

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

مثال 1

ينسخ المثال التالي مَعلمة نموذج واحد من الطلب إلى الطلب المخصّص "MyCustomRequest":

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

مثال 2

ينسخ المثال التالي جميع مَعلمات النموذج إلى الطلب المخصّص "MyCustomRequest":

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

مثال 3

ينسخ المثال التالي ثلاث معلَمات نموذج إلى الطلب المخصّص "MyCustomRequest":

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

مثال 4

في حال توفّر عدة مَعلمات للنماذج بالاسم نفسه، استخدِم البنية التالية:

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

في هذا المثال، يتم نسخ "f1" و"f2"، والقيمة الثانية "f3". إذا كان لدى "f3" قيمة واحدة فقط، لن يتم نسخها.

لا يمكنك استخدام <FormParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: POST
  • نوع الرسالة: ردّ
  • أحد الخيارات التالية (أو كليهما):
    • بيانات النموذج: يجب ضبطها على قيمة معيّنة أو "" (السلسلة الفارغة). على سبيل المثال، باستخدام curl، يمكنك إضافة -d "" إلى طلبك.
    • عنوان Content-Length: يتم ضبط القيمة على 0 (إذا لم تتوفّر أي بيانات في الطلب الأصلي، أو المدة الحالية.) على سبيل المثال، باستخدام curl، أضِف -H "Content-Length: 0" إلى طلبك.

عند نسخ <FormParams>، يضبط <Copy> السمة Content-Type في الرسالة على "Application/x-www-form-urlEncrypt" قبل إرسال الرسالة إلى الخدمة المستهدَفة.

<Headers> (تابع <Copy>)

يتم نسخ عناوين HTTP من رسالة الطلب أو رسالة الاستجابة المحدّدة في السمة source الخاصة بالعنصر <Copy> إلى الطلب أو رسالة الاستجابة المحدّدة في العنصر <AssignTo>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <Header> أو مصفوفة فارغة
العنصر الرئيسي <Copy>
العناصر الثانوية <Header>

يستخدم العنصر <Headers> البنية التالية:

البنية

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

مثال 1

ينسخ المثال التالي عنوان user-agent من الطلب إلى كائن الطلب المخصّص الجديد:

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

مثال 2

لنسخ جميع العناوين، استخدِم عنصر <Headers> فارغًا، كما هو موضّح في المثال التالي:

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

مثال 3

إذا كانت هناك عدة رؤوس تحمل الاسم نفسه، استخدِم الصيغة التالية:

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

في هذا المثال، يتم نسخ "h1" و"h2"، والقيمة الثانية لـ "h3". إذا كان "h3" يحتوي على قيمة واحدة فقط، لن يتم نسخها.

<Path> (تابع <Copy>)

تحدد ما إذا كان يجب نسخ المسار من الطلب المصدر إلى طلب الوجهة. وليس لهذا العنصر أي تأثير في الاستجابة.

إذا كانت القيمة "true"، تنسخ هذه السياسة المسار من رسالة الطلب التي تحدِّدها السمة source المسماة <Copy> إلى رسالة الطلب التي حدّدها العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Path> البنية التالية:

البنية

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

مثال 1

يشير المثال التالي إلى أنّ سياسة AssignMessage يجب أن تنسخ المسار من الطلب المصدر إلى كائن الطلب المخصّص الجديد:

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

لا يمكنك استخدام <Path> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: طلب

<Payload> (تابع <Copy>)

تحدد ما إذا كان يجب نسخ الحمولة من المصدر إلى الوجهة. ويمكن أن يكون المصدر والوجهة طلبات أو ردودًا.

إذا تم ضبط هذه السياسة على "صحيح"، تنسخ هذه السياسة الحمولة من الرسالة التي تحدِّدها السمة source في العنصر <Copy> إلى الرسالة التي يحدّدها العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Payload> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <Payload> على "true" بحيث يتم نسخ حمولة الطلب من الطلب إلى الاستجابة:

<AssignMessage name="copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

<QueryParams> (تابع <Copy>)

يتم نسخ معلَمات سلسلة طلب البحث من الطلب الذي تحدّده السمة source للسمة <Copy> إلى الطلب المحدّد من خلال العنصر <AssignTo>. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <QueryParam> أو مصفوفة فارغة
العنصر الرئيسي <QueryParam>
العناصر الثانوية لا ينطبق

يستخدم العنصر <QueryParams> البنية التالية:

البنية

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

مثال 1

ينسخ المثال التالي مَعلمة طلب البحث "my_param" من الطلب إلى كائن طلب مخصّص جديد:

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

مثال 2

ينسخ المثال التالي جميع معلَمات طلب البحث من الطلب إلى كائن طلب جديد مخصّص:

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

مثال 3

في حال توفّر عدّة مَعلمات طلب بحث بالاسم نفسه، استخدِم البنية التالية:

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

في هذا المثال، يتم نسخ "qp1" و"qp2" والقيمة الثانية لـ "qp3". إذا كان "qp3" يحتوي على قيمة واحدة فقط، لن يتم نسخها.

لا يمكنك استخدام <QueryParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: GET
  • نوع الرسالة: طلب

<ReasonPhrase> (تابع <Copy>)

تحدد ما إذا كان يجب نسخ العبارة السببية من استجابة المصدر إلى استجابة الوجهة. وليس لهذا العنصر أي تأثير في الطلب.

إذا كانت هذه السياسة "صحيح"، تنسخ هذه السياسة ReasonPhrase من الردّ الذي تحدّده السمة source في العنصر <Copy> إلى الردّ الذي يحدّده العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <ReasonPhrase> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <ReasonPhrase> على "true"، ما يدفع <Copy> إلى نسخ عبارة السبب من الاستجابة التلقائية إلى كائن استجابة مخصّص:

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

لا يمكنك استخدام <ReasonPhrase> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: ردّ

<StatusCode> (تابع <Copy>)

تحدد ما إذا كان يتم نسخ رمز الحالة من الاستجابة المصدر إلى استجابة الوجهة. وليس لهذا العنصر أي تأثير في الطلب.

إذا تم ضبط هذه السياسة على "صحيح"، تنسخ هذه السياسة رمز الحالة من رسالة الردّ المحدَّدة في السمة source الخاصة بالعنصر <Copy> إلى رسالة الردّ التي يحدّدها العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <StatusCode> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <StatusCode> على "true"، ما ينسخ رمز الحالة من كائن الاستجابة التلقائي إلى كائن استجابة مخصص جديد:

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

لا يمكنك استخدام <StatusCode> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: ردّ

من الاستخدامات الشائعة لـ <StatusCode> هو ضمان أن تكون استجابة الخادم الوكيل لها الحالة نفسها مثل الاستجابة التي يتم تلقّيها من الاستهداف عند ضبط سمة createNew <AssignTo> على "صحيح".

<Verb> (تابع <Copy>)

تحدد هذه السمة ما إذا كان يتم نسخ فعل HTTP من الطلب المصدر إلى طلب الوجهة. وليس لهذا العنصر أي تأثير في الاستجابة.

إذا كانت القيمة "true"، يتم نسخ الفعل الوارد في السمة source في العنصر <Copy> إلى الطلب المحدَّد في العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Verb> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <Verb> على "true"، ما ينسخ الفعل من الطلب التلقائي إلى طلب مخصَّص جديد:

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

لا يمكنك استخدام <Verb> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: طلب

<Version> (تابع <Copy>)

تحدّد هذه السمة ما إذا كان يتم نسخ نسخة HTTP من الطلب المصدر إلى طلب الوجهة. وليس لهذا العنصر أي تأثير في الاستجابة.

إذا كانت القيمة "صحيح"، انسخ نسخة HTTP التي تم العثور عليها في السمة source للعنصر <Copy> إلى العنصر الذي يحدّده العنصر <AssignTo>.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Copy>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Version> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <Version> على "صحيح" في الطلب، الذي ينسخ النسخة من كائن الطلب التلقائي إلى كائن طلب مخصّص جديد:

<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> شائع لجميع السياسات.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياريّ. إذا حذفت <DisplayName>، سيتم استخدام قيمة السمة name للسياسة.
النوع سلسلة
العنصر الرئيسي <PolicyElement>
العناصر الثانوية لا ينطبق

يستخدم العنصر <DisplayName> البنية التالية:

البنية

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

مثال

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

لا يتضمّن العنصر <DisplayName> أيّ سمات أو عناصر فرعية.

<IgnoreUnresolvedVariables>

لتحديد ما إذا كانت المعالجة تتوقف عند مصادفة متغير لم يتم حله.

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <AssignMessage>
العناصر الثانوية لا ينطبق

اضبط القيمة على true لتجاهل المتغيّرات التي لم يتم حلها ومواصلة المعالجة، وإلا false. القيمة التلقائية هي false.

يختلف ضبط السمة <IgnoreUnresolvedVariables> على true عن ضبط continueOnError للسمة <AssignMessage> على true، لأنّه يكون مخصصًا لإعداد المتغيّرات والحصول عليها. في حال ضبط continueOnError على true، سيتجاهل Edge جميع الأخطاء، وليس فقط الأخطاء التي حدثت عند استخدام المتغيّرات.

يستخدم العنصر <IgnoreUnresolvedVariables> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي <IgnoreUnresolvedVariables> على "true":

<AssignMessage name="ignoreunresolvedvariables">
  <Copy source="response">
    ...
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  </Copy>
</AssignMessage>

<Remove>

إزالة العناوين و/أو مَعلمات طلب البحث و/أو مَعلمات النماذج و/أو حمولة الرسالة من رسالة يمكن أن تكون الرسالة طلبًا أو ردًا. يمكنك تحديد رسالة <Remove> التي يمكن العمل عليها باستخدام العنصر <AssignTo>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع نوع معقد
العنصر الرئيسي <AssignMessage>
العناصر الثانوية <FormParams>
<Headers>
<Payload>
<QueryParams>

تتمثل إحدى حالات الاستخدام الشائعة للسمة <Remove> في حذف معلَمة طلب بحث تحتوي على معلومات حسّاسة من كائن الطلب الوارد، لتجنّب تمريرها إلى خادم الخلفية.

يستخدم العنصر <Remove> البنية التالية:

البنية

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

مثال 1

يؤدي المثال التالي إلى إزالة نص الرسالة من الرد:

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

خلال مسار الاستجابة، تزيل هذه السياسة نص الاستجابة، مع عرض عناوين HTTP فقط إلى البرنامج.

مثال 2

يزيل المثال التالي جميع مَعلمات النموذج ومَعلمة طلب بحث من الطلب الوارد:

<AssignMessage continueOnError="false" enabled="true" name="remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<FormParams> (تابع <Remove>)

يُزيل مَعلمات النموذج المحدّدة من الطلب. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <FormParam> أو مصفوفة فارغة
العنصر الرئيسي <Remove>
العناصر الثانوية <FormParam>

يستخدم العنصر <FormParams> البنية التالية:

البنية

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

مثال 1

يؤدي المثال التالي إلى إزالة ثلاث مَعلمات نموذج من الطلب:

<AssignMessage name="remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

مثال 2

يؤدي المثال التالي إلى إزالة جميع مَعلمات النموذج من الطلب:

<AssignMessage name="remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

مثال 3

في حال توفّر عدة مَعلمات للنماذج بالاسم نفسه، استخدِم البنية التالية:

<AssignMessage name="remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

يؤدي هذا المثال إلى إزالة "f1" و"f2" والقيمة الثانية "f3". إذا كان لدى "f3" قيمة واحدة فقط، لن تتم إزالتها.

لا يمكنك استخدام <FormParams> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: طلب
  • Content-Type: "Application/x-www-form-urlcipher"

<Headers> (تابع <Remove>)

يُزيل هذا الخيار عناوين HTTP المحدّدة من الطلب أو الاستجابة، والتي يحددها العنصر <AssignTo>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <Header> أو مصفوفة فارغة
العنصر الرئيسي <Remove>
العناصر الثانوية <Header>

يستخدم العنصر <Headers> البنية التالية:

البنية

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

مثال 1

يؤدي المثال التالي إلى إزالة عنوان user-agent من الطلب:

<AssignMessage name="remove-headers-1">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

مثال 2

يؤدي المثال التالي إلى إزالة جميع العناوين من الطلب:

<AssignMessage name="remove-headers-2">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

مثال 3

إذا كانت هناك عدة رؤوس تحمل الاسم نفسه، استخدِم الصيغة التالية:

<AssignMessage name="remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

يؤدي هذا المثال إلى إزالة "h1" و"h2" والقيمة الثانية "h3" من الطلب. إذا كان "h3" يحتوي على قيمة واحدة فقط، لن تتم إزالتها.

<Payload> (تابع <Remove>)

تحدِّد هذه السياسة ما إذا كان <Remove> سيحذف الحمولة في الطلب أو الاستجابة، الذي يحدده العنصر <AssignTo>. اضبط القيمة على "true" لمحو الحمولة، وإلا سيتم الضبط على "false". القيمة التلقائية هي "false".

القيمة التلقائية خطأ
هل هي مطلوبة؟ اختياري
النوع منطقي
العنصر الرئيسي <Remove>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Payload> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي <Payload> على "true" ليتم محو حمولة الطلب:

<AssignMessage name="remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<QueryParams> (تابع <Remove>)

يُزيل مَعلمات طلب البحث المحدّدة من الطلب. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة من عناصر <QueryParam> أو مصفوفة فارغة
العنصر الرئيسي <Remove>
العناصر الثانوية <QueryParam>

يستخدم العنصر <QueryParams> البنية التالية:

البنية

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

مثال 1

يزيل المثال التالي مَعلمة طلب بحث واحدة من الطلب:

<AssignMessage name="remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

مثال 2

يؤدي المثال التالي إلى إزالة جميع مَعلمات طلب البحث من الطلب:

<AssignMessage name="remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

مثال 3

في حال توفّر عدّة مَعلمات طلب بحث بالاسم نفسه، استخدِم البنية التالية:

<AssignMessage name="remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

يؤدي هذا المثال إلى إزالة "qp1" و"qp2" والقيمة الثانية لـ "qp3" من الطلب. وإذا كانت يحتوي على قيمة واحدة فقط لـ "qp3"، لن تتم إزالتها.

مثال 4

يزيل المثال التالي مَعلمة طلب البحث apikey من الطلب:

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

لا يمكنك استخدام <QueryParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: GET
  • نوع الرسالة: طلب

<Set>

لضبط المعلومات في الطلب أو رسالة الرد، التي يتم تحديدها من خلال العنصر <AssignTo>. يستبدل <Set> العناوين أو المَعلمات المتوفّرة في الرسالة الأصلية. لإنشاء عنوان جديد أو مَعلمة جديدة، استخدِم العنصر <Add> بدلاً من ذلك.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع نوع معقد
العنصر الرئيسي <AssignMessage>
العناصر الثانوية <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

يستخدم العنصر <Set> البنية التالية:

البنية

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

مثال 1

يوضّح المثال التالي العنصر <Set>:

<AssignMessage continueOnError="false" enabled="true" name="set-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
    <QueryParams>
      <QueryParam name="name">{request.header.name}</QueryParam>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
    <!-- <Verb>GET</Verb> -->
    <Payload contentType="text/plain">42</Payload>
    <Path/>
    <ReasonPhrase>Bad request</ReasonPhrase>
    <StatusCode>400</StatusCode>
    <Verb>POST</Verb>
    <Verb>{my_variable}</Verb>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<FormParams> (تابع <Set>)

تستبدل مَعلمات النموذج الحالية في طلب معيّن وتستبدلها بالقيم الجديدة التي تحدّدها بهذا العنصر. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <FormParam>
العنصر الرئيسي <Set>
العناصر الثانوية <FormParam>

يستخدم العنصر <FormParams> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي معلَمة نموذج تُسمى "myparam" على قيمة المتغيّر request.header.myparam في طلب مخصّص جديد:

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

لا يمكنك استخدام <FormParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: POST
  • نوع الرسالة: طلب

عند تحديد مَعلمات نماذج فارغة في سياستك (<Add><FormParams/></Add>)، لا تُضيف السياسة أي مَعلمات للنماذج. وينطبق ذلك تمامًا على حذف <FormParams>.

تغيّر الدالة <Set> Content-Type للرسالة إلى "Application/x-www-form-urlcipher" قبل إرسالها إلى نقطة النهاية المستهدفة.

<Headers> (تابع <Set>)

يستبدل عناوين HTTP الحالية في الطلب أو الاستجابة، والتي يتم تحديدها من خلال العنصر <AssignTo>.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <Header>
العنصر الرئيسي <Set>
العناصر الثانوية <Header>

يستخدم العنصر <Headers> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي عنوان user-agent على قيمة المتغيّر request.header.user-agent:

<AssignMessage name="set-headers-1">
  <Set>
    <Headers>
      <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

في حال تحديد عناوين فارغة في سياستك (<Add><Headers/></Add>)، لا تضيف السياسة أي عناوين. ويماثل حذف <Headers>.

<Path> (تابع <Set>)

<Payload> (تابع <Set>)

لتحديد نص الرسالة لطلب أو استجابة، الذي يحدده العنصر <AssignTo>. ويمكن أن تكون الحمولة أي نوع محتوى صالح، مثل نص عادي أو JSON أو XML.

القيمة التلقائية سلسلة فارغة
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <Set>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Payload> البنية التالية:

البنية

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

مثال 1

يحدد المثال التالي حمولة نص عادي:

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

مثال 2

يحدّد المثال التالي حمولة JSON:

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

مثال 3

يدرج المثال التالي قيم المتغيّر في الحمولة من خلال إحاطة أسماء المتغيرات بأقواس معقوفة:

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

في الإصدارات القديمة من Apigee Edge، على سبيل المثال، قبل الإصدار 16.08.17 من السحابة الإلكترونية، لم تكن تستطيع استخدام الأقواس المعقوفة للإشارة إلى مراجع المتغيّر ضمن حمولات JSON. في هذه الإصدارات، كان يجب استخدام السمتَين variablePrefix وvariableSuffix لتحديد أحرف المحدِّد، واستخدام هذه السمتَين لالتفاف أسماء المتغيّرات، على النحو التالي:

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

لا تزال هذه البنية القديمة تعمل.

مثال 4

يتم التعامل مع محتوى <Payload> باعتباره نموذج رسالة. وهذا يعني أنّ سياسة AssignMessage تستبدل المتغيّرات الملفوفة في أقواس معقوفة بقيمة المتغيّرات المُشار إليها في وقت التشغيل.

يستخدم المثال التالي بنية الأقواس المعقوفة لضبط جزء من الحمولة على قيمة متغيّرة:

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

يوضِّح الجدول التالي سمات <Payload>:

السمة الوصف التواجد في المنزل النوع
contentType

وفي حال تحديدها، يتم تخصيص قيمة contentType لعنوان HTTP Content-Type.

اختياري سلسلة
variablePrefix تحدد بشكل اختياري المحدد الرئيسي في متغير التدفق. ويتم الضبط تلقائيًا على "{". ولمزيد من المعلومات، يُرجى الاطّلاع على مرجع متغيّرات التدفق. اختياري شار
variableSuffix تحدد بشكل اختياري المحدد اللاحق في متغير التدفق. يتم الضبط تلقائيًا على "}". لمزيد من المعلومات، يُرجى الاطّلاع على مرجع متغيّرات التدفق. اختياري شار

<QueryParams> (تابع <Set>)

تستبدل معلَمات طلب البحث الحالية في الطلب بقيم جديدة. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع مصفوفة عناصر <QueryParam>
العنصر الرئيسي <Set>
العناصر الثانوية <QueryParam>

يستخدم العنصر <QueryParams> البنية التالية:

البنية

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

مثال 1

يحدّد المثال التالي معلمة طلب البحث "address" على قيمة المتغيّر request.header.address:

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

لا يمكنك استخدام <QueryParams> إلا عند استيفاء المعايير التالية:

  • فعل HTTP: GET
  • نوع الرسالة: طلب

إذا حدّدت معلَمات طلب بحث فارغة في سياستك (<Set><QueryParams/></Set>)، لا تضبط السياسة أي مَعلمات لطلب البحث. وينطبق ذلك تمامًا على حذف <QueryParams>.

<ReasonPhrase> (تابع <Set>)

لضبط عبارة السبب في الردّ. يتم ذلك عادةً لتصحيح الأخطاء بالتزامن مع <StatusCode>. وليس لهذا العنصر أي تأثير في الطلب.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <Set>
العناصر الثانوية لا ينطبق

يستخدم العنصر <ReasonPhrase> البنية التالية:

البنية

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

مثال 1

يعرّف المثال التالي عبارة سبب بسيطة:

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

مثال 2

يتم التعامل مع محتوى <ReasonPhrase> باعتباره نموذج رسالة. وهذا يعني أنه سيتم في وقت التشغيل استبدال اسم المتغيّر المحاط بأقواس معقوفة بقيمة المتغير المُشار إليه، كما هو موضّح في المثال التالي:

<AssignMessage name="set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

لا يمكنك استخدام <ReasonPhrase> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: ردّ

<StatusCode> (تابع <Set>)

لضبط رمز الحالة على الردّ. وليس لهذا العنصر أي تأثير في الطلب.

القيمة التلقائية "200" (عند ضبط السمة createNew في <AssignTo> على "صحيح")
هل هي مطلوبة؟ اختياري
النوع سلسلة أو variable
العنصر الرئيسي <Set>
العناصر الثانوية لا ينطبق

يستخدم العنصر <StatusCode> البنية التالية:

البنية

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

مثال 1

يحدد المثال التالي رمز حالة بسيطًا:

<AssignMessage name="set-statuscode-1">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

مثال 2

يتم التعامل مع محتوى <StatusCode> باعتباره نموذج رسالة. وهذا يعني أنه سيتم في وقت التشغيل استبدال اسم المتغيّر المحاط بأقواس معقوفة بقيمة المتغير المُشار إليه، كما هو موضّح في المثال التالي:

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

لا يمكنك استخدام <StatusCode> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: ردّ

<Verb> (تابع <Set>)

لضبط فعل HTTP في الطلب. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة أو variable
العنصر الرئيسي <Set>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Verb> البنية التالية:

البنية

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

مثال 1

يحدد المثال التالي فعلاً بسيطًا في الطلب:

<AssignMessage name="set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

مثال 2

يتم التعامل مع محتوى <Verb> باعتباره نموذج رسالة. وهذا يعني أنّه سيتم في وقت التشغيل استبدال اسم المتغيّر المحاط بأقواس معقوفة بقيمة المتغير المُشار إليه.

يستخدم المثال التالي متغيرًا لتعبئة فعل ما:

<AssignMessage name="set-verb-2">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

لا يمكنك استخدام <Verb> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: طلب

<Version> (تابع <Set>)

لضبط إصدار HTTP في أحد الطلبات. وليس لهذا العنصر أي تأثير في الاستجابة.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع سلسلة أو variable
العنصر الرئيسي <Set>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Version> البنية التالية:

البنية

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

مثال 1

يضبط المثال التالي رقم الإصدار على "1.1":

<AssignMessage name="set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

مثال 2

فيما يلي استخدام متغير بين أقواس معقوفة لتعيين رقم الإصدار:

<AssignMessage name="set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

يتم التعامل مع محتوى <Version> باعتباره نموذج رسالة. وهذا يعني أنه سيتم في وقت التشغيل استبدال اسم المتغيّر المحاط بأقواس معقوفة بقيمة المتغير المُشار إليه.

لا يمكنك استخدام <Version> إلا عند استيفاء المعايير التالية:

  • نوع الرسالة: طلب

إنشاء رسائل طلب مخصّصة

يمكنك استخدام سياسة AssignMessage لإنشاء رسالة طلب مخصّصة. بعد إنشاء طلب مخصّص، يمكنك استخدامه بالطرق التالية:

  • الوصول إلى متغيّراتها في السياسات الأخرى
  • تمريره إلى خدمة خارجية

لإنشاء رسالة طلب مخصّصة، استخدِم العنصر <AssignTo> في سياسة AssignMessage. اضبط createNew على "true" وحدِّد اسم الرسالة الجديدة في نص العنصر، كما يبيِّن المثال التالي:

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

بشكل تلقائي، لا يفعل Edge أي شيء مع رسالة الطلب المخصّصة. بعد إنشائه، يواصل Edge تنفيذ العملية مع الطلب الأصلي. لاستخدام الطلب المخصّص، أضِف سياسة مثل سياسة وسيلة شرح الخدمة إلى الخادم الوكيل التي يمكنها تمرير الطلب المخصّص إلى خدمة خارجية.

تنشئ الأمثلة التالية رسائل طلب مخصّصة:

مثال 1

ينشئ المثال التالي كائن طلب مخصصًا باستخدام "Assign Message" (تعيين رسالة):

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

هذا المثال:

  • ينشئ كائن رسالة طلب جديد يُسمى "MyCustomRequest".
  • في MyCustomRequest، تعمل هذه السياسة على إجراء ما يلي:
    • سيتم نسخ قيمة عنوان HTTP user-agent من الطلب الوارد إلى الرسالة الجديدة. بما أنّ السمة <Copy> تستخدم مرجعًا مطلقًا لمتغيّر التدفق user-agent، لن تحتاج إلى تحديد السمة source على <Copy>.
    • تضبط معلَمة طلب البحث address في الرسالة المخصّصة على قيمة معلَمة طلب البحث addy للطلب الوارد.
    • لضبط فعل HTTP على GET.
  • لضبط <IgnoreUnresolvedVariables> على "خطأ". عندما تكون قيمة <IgnoreUnresolvedVariables> "خطأ"، وإذا لم يكن أحد المتغيّرات التي حاولت السياسة إضافتها متوفرًا، سيتوقّف Edge عن المعالجة في مسار واجهة برمجة التطبيقات.

مثال 2

في ما يلي مثال آخر يوضّح كيفية إنشاء كائن طلب مخصّص باستخدام ميزة 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 createNew="false" type="request"></AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

الفيديوهات

يمكنك مشاهدة الفيديوهات التالية للاطّلاع على مزيد من المعلومات عن سياسة AssignMessage.

حملة فيديو الوصف
أهمية تعيين سياسة الرسائل تعرَّف على مزايا استخدام سياسة AssignMessage لتعديل طلب أو استجابة واجهة برمجة التطبيقات بدون تعديل رمز الخلفية.
نسخ عناصر واجهة برمجة التطبيقات باستخدام سياسة AssignMessage يمكنك نسخ العناصر من طلب أو استجابة من واجهة برمجة التطبيقات وإنشاء طلب أو عنصر استجابة جديد باستخدام سياسة AssignMessage.
إزالة عناصر واجهة برمجة التطبيقات باستخدام سياسة AssignMessage يمكنك إزالة عناصر واجهة برمجة التطبيقات وتعديل واجهة برمجة التطبيقات قبل وصولها إلى الواجهة الخلفية المستهدفة باستخدام سياسة AssignMessage.
إضافة عناصر واجهة برمجة التطبيقات وضبطها باستخدام سياسة AssignMessage يمكنك تغيير طلب أو استجابة واجهة برمجة التطبيقات عن طريق إضافة مَعلمات طلب البحث أو العناوين أو معلَمات النموذج أو الحمولات باستخدام سياسة AssignMessage.
إنشاء متغيّرات مخصّصة باستخدام سياسة AssignMessage اضبط متغيّرات التدفق المخصّصة باستخدام سياسة AssignMessage واستفِد من المتغيّرات في السياسات الأخرى في الخادم الوكيل لواجهة برمجة التطبيقات.
إنشاء عناصر جديدة للطلب أو الاستجابة باستخدام سياسة AssignMessage يمكنك إنشاء عناصر استجابة أو طلبات جديدة من واجهة برمجة التطبيقات باستخدام سياسة AssignMessage في وقت تشغيل واجهة برمجة التطبيقات.
إنشاء واجهة برمجة تطبيقات وهمية باستخدام سياسة AssignMessage يمكنك إنشاء واجهة برمجة تطبيقات REST API وهمية وبسيطة عن طريق إضافة السياسة AssignMessage في مسار الردّ.
ضبط الحمولة أو تعديلها باستخدام سياسة AssignMessage يمكنك تحويل طلب REST إلى طلب SOAP عن طريق ضبط SOAP Payload باستخدام سياسة AssignMessage في وقت تشغيل واجهة برمجة التطبيقات.

رموز الخطأ

يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد للأخطاء للتعامل معها. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

رمز الخطأ رموز حالة HTTP السبب إصلاح
steps.assignmessage.SetVariableFailed 500 تعذّر على السياسة ضبط متغيّر. راجِع سلسلة الخطأ لمعرفة اسم المتغيّر الذي لم يتم حله.
steps.assignmessage.VariableOfNonMsgType 500

يحدث هذا الخطأ إذا تم ضبط السمة source في العنصر <Copy> على متغيّر ليس من نوع message.

تمثل متغيرات نوع الرسالة طلبات واستجابات HTTP كاملة. وتكون متغيّرات تدفق Edge المدمَجة request وresponse وmessage من نوع الرسالة. لمزيد من المعلومات عن متغيّرات الرسائل، اطّلِع على مرجع المتغيّرات.

steps.assignmessage.UnresolvedVariable 500

يحدث هذا الخطأ إذا كان أحد المتغيّرات المحددة في سياسة "تعيين الرسالة":

  • خارج النطاق (غير متاحة في المسار المحدّد الذي يتم فيه تنفيذ السياسة)
  • أو
  • لا يمكن حلها (غير محددة)

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

اسم الخطأ السبب إصلاح
InvalidIndex إذا كان الفهرس المحدَّد في العنصرَين <Copy> و/أو <Remove> في سياسة تخصيص الرسالة هو 0 أو رقمًا سالبَين، سيتعذّر نشر الخادم الوكيل لواجهة برمجة التطبيقات.
InvalidVariableName إذا كان العنصر الفرعي <Name> فارغًا أو غير محدَّد في العنصر <AssignVariable>، سيتعذّر نشر الخادم الوكيل لواجهة برمجة التطبيقات بسبب عدم توفّر اسم متغيّر صالح يتم تخصيص قيمة له. يجب إدخال اسم متغيّر صالح.
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="VariableOfNonMsgType"></faultrule><FaultRule name="Assign Message Faults">
    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>

المخططات

يتم تحديد كل نوع سياسة من خلال مخطّط XML (.xsd). تتوفّر مخطّطات السياسات كمرجع على GitHub.

مواضيع ذات صلة

تتوفّر نماذج العمل من سياسة AssignMessage في نماذج النظام الأساسي لواجهة برمجة التطبيقات.

للاطّلاع على مثال أكثر تقدّمًا حول كيفية إلغاء target.url من ProxyEndpoint، يُرجى الاطّلاع على مقالة منتدى Apigee هذه.

وللاطِّلاع على "ضبط مسار" عمليًا في سياسة ServiceCallout، يمكنك الاطّلاع على هذه التعلّم من خلال تنفيذ مثال في نماذج Apigee GitHub. ما عليك سوى استنساخ المستودع واتّباع التعليمات الواردة في ذلك الموضوع. يستخدم هذا المثال سياسة AssignMessage لضبط مسار طلب، ثم تستخدِم سياسة "وسيلة شرح الخدمة" لإرسال الطلب إلى خدمة خارجية.