سياسة استخراج المتغيرات

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

الموضوع

تعمل سياسة استخراج المتغيّرات على استخراج المحتوى من طلب أو استجابة وضبط قيمة متغيّر لهذا المحتوى. ويمكنك استخراج أي جزء من الرسالة، بما في ذلك العناوين ومسارات معرّف الموارد المنتظم (URI) وحمولات JSON/XML ومَعلمات النماذج ومَعلمات طلب البحث. تعمل السياسة من خلال تطبيق نمط نص على محتوى الرسالة، وعند العثور على مطابقة، يتم ضبط متغيّر بمحتوى الرسالة المحدَّد.

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

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

الفيديوهات الطويلة

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

عيّنات

توضّح نماذج الرموز لهذه السياسة كيفية استخراج المتغيّرات من الأنواع التالية من العناصر:

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
 <DisplayName>AssignPayload</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="w">
      <Pattern ignoreCase="true">{firstWeather}</Pattern>
   </QueryParam>
   <QueryParam name="w.2">
     <Pattern ignoreCase="true">{secondWeather}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
    <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetHeader</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add> 
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

لمحة عن سياسة المتغيّرات

ينشئ مطوّرو واجهات برمجة التطبيقات خوادم وكيلة لواجهة برمجة التطبيقات تعمل بشكل مختلف استنادًا إلى محتوى الرسائل، بما في ذلك العناوين ومسارات معرّف الموارد المنتظم (URI) وحمولات البيانات ومَعلمات طلبات البحث. وغالبًا ما يستخرج الخادم الوكيل جزءًا من هذا المحتوى لاستخدامه في عبارة شرط. استخدِم سياسة "المتغيّرات" لتنفيذ هذا الإجراء.

عند تحديد سياسة استخراج المتغيرات، يمكنك اختيار:

• أسماء المتغيرات التي سيتم ضبطها
• مصدر المتغيّرات
• عدد المتغيّرات المطلوب استخراجها وضبطها

عند تنفيذ السياسة، تطبّق السياسة نمطًا نصيًا على المحتوى، وتضبط قيمة المتغيّر المحدَّد مع المحتوى عند العثور عليها. وبعد ذلك، يمكن للسياسات والرموز الأخرى أن تستهلك هذه المتغيّرات لتفعيل السلوك الديناميكي أو لإرسال بيانات النشاط التجاري إلى Edge API Analytics.

للتعرّف على كيفية استخدام المتغيّرات الاستخراجية لإنشاء تقارير "إحصاءات Google" تستند إلى المحتوى، يُرجى الاطّلاع على المقالة تحليل محتوى رسالة واجهة برمجة التطبيقات باستخدام إحصاءات مخصّصة.

النطاق

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

• PreFlow: ProxyEndpoint وTargetEndpoint (الطلب والاستجابة)
• PostFlow: ProxyEndpoint وTargetEndpoint (الطلب والاستجابة)
• PostClientFlow: ProxyEndpoint (للاستجابة فقط، باستخدام سياسة تسجيل الرسائل)
• تدفقات الأخطاء

لمحة عن المطابقة وإنشاء المتغيّرات

تعمل سياسة استخراج المتغيّرات على استخراج المعلومات من طلب أو ردّ وكتابة هذه المعلومات في متغيّر. بالنسبة إلى كل نوع من المعلومات التي يمكنك استخراجها، مثل مسار معرّف الموارد المنتظم (URI) أو بيانات XML، عليك تحديد النمط المطلوب مطابقته واسم المتغيّر المستخدَم للاحتفاظ بالمعلومات التي تم استخراجها.

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

مطابقة مسارات معرّف الموارد المنتظم (URI) ومَعلمات طلب البحث والعناوين ومَعلمات النماذج والمتغيرات

عند استخراج المعلومات من مسار معرّف الموارد المنتظم (URI) ومَعلمات طلب البحث والعناوين ومَعلمات النماذج والمتغيّرات، يمكنك استخدام علامة <Pattern> لتحديد نمط واحد أو أكثر لمطابقته. على سبيل المثال، يعرض مثال السياسة التالي نمط مطابقة واحدًا لمسار معرّف الموارد المنتظم (URI):

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

في هذا المثال، يتم ضبط المتغيّر urirequest.pathSeg على ما يظهر في client.pathsuffix بعد "/a/". على سبيل المثال، لنفترض أنّ المسار الأساسي للخادم الوكيل لواجهة برمجة التطبيقات هو /basepath/v1 . عند استخدام طلب وارد إلى http://myCo.com/basepath/v1/a/b، يتم ضبط المتغيّر على "b".

تحديد أنماط متعددة

يمكنك تحديد أشكال متعددة لمطابقتها، بما يتوافق مع علامات <Pattern>، حيث:

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

في المثال التالي، يتم إنشاء سياسة تحتوي على ثلاثة أنماط مطابقة لمسار معرّف الموارد المنتظم (URI):

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

لنفترض أنّه في الخادم الوكيل لواجهة برمجة التطبيقات الذي يستند إلى مسار أساسي /basepath/v1، يكون عنوان URL للطلب الوارد إلى الخادم الوكيل لواجهة برمجة التطبيقات على النحو التالي:

http://myCo.com/basepath/v1/a/b

في هذا المثال، يتطابق النمط الأول مع معرّف الموارد المنتظم (URI) ويتم ضبط المتغيّر urirequest.pathSeg على "b".

إذا كان عنوان URL للطلب هو:

http://myCo.com/basepath/v1/a/b/c/d

...يتطابق عندها النمط الثالث ويتم ضبط المتغير urirequest.pathSeg على "d".

تحديد أنماط بمتغيرات متعددة

ويمكنك تحديد متغيّرات متعددة في النمط المطابق. على سبيل المثال، يمكنك تحديد نمط مطابقة يتضمّن متغيّرَين:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

لنفترض أيضًا وجود خادم وكيل لواجهة برمجة التطبيقات مع مسار أساسي /basepath/v1 لعنوان URL للطلب الوارد:

http://myCo.com/basepath/v1/a/b/c/d

...يتم ضبط المتغيّر urirequest.pathSeg1 على "b" والمتغير urirequest.pathSeg2 على "d".

مطابقة عدة مثيلات في النمط

يمكنك أيضًا مطابقة الأنماط عندما يكون هناك عدة نُسخ من عنصر يحمل الاسم نفسه. على سبيل المثال، يمكنك تقديم طلب يحتوي على معلَمات طلب بحث متعددة أو عدة عناوين تحمل الاسم نفسه. يحتوي الطلب التالي على مَعلمتَي طلب بحث باسم "w":

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

للإشارة إلى معلَمات طلب البحث هذه في سياسة متغيرات طلب البحث، عليك استخدام الفهارس، حيث لا تحتوي الحالة الأولى لمَعلمة طلب البحث على فهرس، والمثال الثاني في الفهرس 2، والثالث في الفهرس 3، وهكذا. على سبيل المثال، تعمل السياسة التالية على استخراج قيمة مَعلمة طلب البحث الثانية المسماة "w" في الطلب:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <QueryParam name="w.2">
      <Pattern ignoreCase="true">{secondW}</Pattern>
   </QueryParam>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

تم ضبط المتغيّر urirequest.secondW على "2". في حال حذف مَعلمة طلب البحث الثانية من الطلب، يكون المتغيّر urirequest.secondW فارغًا. يمكنك استخدام الفهرسة في أي وقت يتضمّن الطلب عدة عناصر تحمل الاسم نفسه.

استخدام رموز خاصة في النمط

عند مطابقة مسارات معرّفات الموارد المنتظمة (URI)، يمكنك استخدام حرفَي البدل "*" و "**" في النمط، حيث:

• يتطابق "*" مع أي مقطع واحد من المسار
• يتطابق "**" مع مقاطع متعددة للمسار

على سبيل المثال، يمكنك تحديد أنماط لعنصر <URIPath> كما هو موضّح أدناه:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

يطابق النمط الأول الطلبات ذات المسارات اللاحقة (جزء من مسار معرّف الموارد المنتظم الذي يلي المسار الأساسي) مثل "/a/b/c" و"/a/foo/bar" وما إلى ذلك. ويطابق النمط الثاني أي عدد من قطاعات المسارات بعد "/a/"، مثل "/a/foo/bar/baz/c"، بالإضافة إلى "/a/b/c" و "/a/foo".

عند تحديد أنماط لمَعلمات طلب البحث والعناوين ومَعلمات النماذج، يتم تحديد "*"character لمطابقة أي عدد من الأحرف. على سبيل المثال، عند مطابقة عنوان، يجب تحديد النمط على النحو التالي:

*;charset={encoding}

يتطابق هذا النمط مع القيمتين "text/xml;charset=UTF-16" و"application/xml;charset=ASCII".

إذا كانت القيمة التي تم تمريرها إلى سياسة استخراج المتغيرات تحتوي على حرف خاص، مثل "{"، استخدم الحرف "%" لتخطيها. يؤدي المثال التالي إلى تجنّب الحرفين "{" و"} في النمط لأنّه يتم استخدامهما كأحرف حرفية في قيمة معلَمة طلب البحث:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

في هذا المثال، يتطابق النمط مع القيمة "{user} ستيف" ولكن ليس مع القيمة "المستخدم ستيف".

مطابقة JSON وXML

عند استخراج البيانات من JSON وXML، يمكنك تحديد علامة <Variable> واحدة أو أكثر في السياسة. تحدد العلامة <Variable> اسم متغير الوجهة الذي يتم فيه تخزين المعلومات المستخرجة، واسم متغير JsonPath (JSON) أو XPATH (XML) للمعلومات المستخرجة.

يتم تقييم جميع علامات <Variable> في السياسة كي تتمكّن من تعبئة متغيّرات متعددة من سياسة واحدة. إذا لم يتم تقييم العلامة <Variable> للحصول على حقل صالح في JSON أو XML، لن يتم إنشاء المتغيّر المقابل.

يوضّح المثال التالي سياسة استخراج المتغيّرات التي تملأ متغيّرَين من نص JSON للاستجابة:

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

الكتابة باستخدام المتغيّر نفسه في عدة أماكن

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

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

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

التحكّم في ما يحدث عندما لا يحدث أي تطابق

إذا لم يتطابق النمط، لن يتم إنشاء المتغير المقابل. وبالتالي، إذا كانت سياسة أخرى تشير إلى المتغيّر، يمكن أن يؤدي ذلك إلى حدوث خطأ.

أحد الخيارات هو ضبط <IgnoreUnresolvedVariables> على "صحيح" في سياسة تشير إلى المتغيّر لإعداد السياسة للتعامل مع أي متغيّر غير قابل للتحليل كسلسلة فارغة (قيمة فارغة):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

مرجع العنصر

يصف مرجع العناصر عناصر وسمات سياسة استخراج المتغيرات.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName>Extract Variables 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

سمات <استخراجVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

العنصر <DisplayName>

استخدِم هذه السمة بالإضافة إلى السمة name لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

عنصر <المصدر>

(اختياري) تحدِّد المتغيّر المطلوب تحليله. ويتم ضبط قيمة <Source> تلقائيًا على message. قيمة message حساسة للسياق. في مسار الطلب، يتم التعامل مع message إلى رسالة الطلب. في مسار الاستجابة، يتم التعامل مع السمة message مع رسالة الرد.

غالبًا ما تستخدم هذه السياسة لاستخراج المعلومات من طلب أو رسالة ردّ، ولكن يمكنك استخدامها لاستخراج المعلومات من أي متغيّر. على سبيل المثال، يمكنك استخدامها لاستخراج المعلومات من كيان تم إنشاؤه من خلال سياسة AccessEntity، أو من البيانات التي تعرضها سياسة وسائل شرح الخدمات، أو لاستخراج المعلومات من عنصر XML أو JSON.

في حال تعذَّر حل <Source> أو تم تحويلها إلى نوع غير الرسائل، لن تستجيب السياسة.

<Source clearPayload="true|false">request</Source>

السمات

عنصر <VariablePrefix>

(اختياري) يتم إنشاء اسم المتغيّر الكامل من خلال ضم <VariablePrefix> والنقطة والاسم الذي تحدّده بين {الأقواس المعقوفة} في العنصر <Pattern> أو العنصر <Variable>. على سبيل المثال: myprefix.id أو myprefix.dbncode أو myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

على سبيل المثال، لنفترض أن قيمة الاسم هي "user".

• إذا لم يتم تحديد <VariablePrefix>، يتم تعيين القيم المستخرَجة إلى متغيّر باسم user.
• إذا تم تحديد <VariablePrefix> على أنه myprefix، سيتم تعيين القيم المستخرَجة إلى متغيّر باسم myprefix.user.

عنصر <تجاهلUnresolvedVariables>

(اختياري) اضبط القيمة على true للتعامل مع أي متغيّر غير قابل للتحليل كسلسلة فارغة (فارغ). اضبط القيمة على false إذا كنت تريد أن تعرض السياسة خطأ عندما يكون أي متغيّر مُشار إليه غير قابل للتحليل.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

إذا لم يتم حلّ مرجع XPath في <XMLPayload>، تعرض السياسة الخطأ التالي:

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

عنصر <URIPath>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). لاستخراج قيمة من وكيل.pathsuffix لرسالة مصدر الطلب. والمسار المطبَّق على النمط هوproxy.pathsuffix، لأنّه لا يتضمّن المسار الأساسي للخادم الوكيل لواجهة برمجة التطبيقات. إذا تم تحويل الرسالة المصدر إلى نوع رسالة الردّ، لن يكون لهذا العنصر أي تأثير.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

من الممكن استخدام عناصر <Pattern> متعددة:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

السمات

عنصر <QueryParam>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). لاستخراج قيمة من معلمة طلب البحث المحددة لرسالة مصدر request. إذا تم تحويل الرسالة المصدر إلى نوع رسالة رد، لن يكون لهذا العنصر أي تأثير.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

إذا كانت مَعلمات طلبات بحث متعدّدة تحمل الاسم نفسه، استخدِم الفهارس للإشارة إلى المَعلمات:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

السمات

عنصر <Header>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). لاستخراج قيمة من عنوان HTTP المحدد لرسالة الطلب أو الاستجابة المحددة وإذا كانت عدة عناوين تحمل الاسم نفسه، يتم تخزين قيمها في مصفوفة.

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

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

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

أو ما يلي لإدراج جميع العناوين في الصفيف:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

السمات

عنصر <FormParam>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). لاستخراج قيمة من معلمة النموذج المحددة لرسالة request أو response المحددة. لا يمكن استخراج مَعلمات النموذج إلا عندما يكون عنوان Content-Type للرسالة المحددة هو application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

السمات

عنصر <Variable>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). تحدد اسم المتغيّر الذي يتم استخراج قيمة منه.

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

لاستخراج قيمتين من المتغير:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

السمات

عنصر <JSONPayload>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). تحدِّد الرسالة بتنسيق JSON التي سيتم استخراج قيمة المتغيّر منها. لا يتم استخراج تنسيق JSON إلا إذا كان عنوان نوع المحتوى للرسالة هو application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

عنصر <JSONPayload>/<Variable>

(مطلوبة ضمن عنصر JSONPayload) تحدّد المتغيّر الذي يتم فيه تحديد القيمة المستخرَجة. يمكنك تضمين عدة علامات <Variable> في العنصر <JSONPayload> لتعبئة متغيّرات متعددة.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

السمات

عنصر <JSONPayload>/<Variable>/<JSONPath>

(مطلوب ضمن العنصر JSONPayload:Variable). تحدّد مسار JSON المستخدَم لاستخراج قيمة من رسالة بتنسيق JSON.

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

عنصر <XMLPayload>

(اختياري، ولكن يُرجى الاطّلاع على صف "التواجد" في الجدول أدناه للحصول على مزيد من المعلومات). تحدِّد الرسالة بتنسيق XML التي سيتم استخراج قيمة المتغيّر منها. يتم استخراج حمولات XML فقط عندما يكون عنوان Content-Type للرسالة هو text/xml أو application/xml أو application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>

السمات

العنصر <XMLPayload>/<Namespaces>

(اختياري) تحدد مساحة الاسم التي سيتم استخدامها في تقييم XPath. إذا كنت تستخدم مساحات الاسم في تعبيرات XPath، عليك الإفصاح عن مساحات الاسم هنا، كما هو موضّح في المثال التالي.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

إذا كنت لا تستخدم مساحات أسماء في تعبيرات XPath، يمكنك حذف العنصر <Namespaces> أو التعليق عليه على النحو الموضّح في المثال التالي:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

السمات

عنصر <XMLPayload>/<Variable>

(اختياري) تحدِّد هذه السمة المتغيّر الذي سيتم تخصيص القيمة المستخرجة له.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

السمات

عنصر <XMLPayload>/<Variable>/<XPath>

(مطلوب ضمن العنصر XMLPayload:Variable). تحدد هذه السمة XPath المحدّد للمتغيّر. إنّ تعبيرات XPath 1.0 فقط هي المتوافقة.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

مثال مع مساحة اسم إذا كنت تستخدم مساحات الاسم في تعبيرات XPath، عليك الإفصاح عن مساحات الاسم في القسم <XMLPayload><Namespaces> من السياسة.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

مرجع الخطأ

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

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

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

أخطاء النشر

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

متغيرات الخطأ

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

مثال على الردّ على الخطأ

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

مثال لقاعدة خطأ

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

المخططات

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

تحليل محتوى رسالة واجهة برمجة التطبيقات باستخدام الإحصاءات المخصّصة

مرجع المتغيّرات