خط‌مشی ExtractVariables

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

چه

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

اگرچه اغلب از این خط‌مشی برای استخراج اطلاعات از پیام درخواست یا پاسخ استفاده می‌کنید، می‌توانید از آن برای استخراج اطلاعات از منابع دیگر نیز استفاده کنید، ازجمله نهادهای ایجادشده توسط خط‌مشی AccessEntity، اشیاء XML، یا اشیاء JSON.

پس‌از استخراج محتوای پیام مشخص‌شده، می‌توانید به متغیر در خط‌مشی‌های دیگر به‌عنوان بخشی از پردازش درخواست و پاسخ ارجاع دهید.

ویدیوها

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

نمونه‌ها

این نمونه‌های کد خط‌مشی نشان می‌دهند که چگونه متغیرها را از انواع زیر آرتیفکت‌ها استخراج کنید:

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

درباره خط‌مشی ExtractVariables

توسعه‌دهندگان API پراکسی‌های API می‌سازند که براساس محتوای پیام‌ها، ازجمله سرایندها، مسیرهای URI، بارها، و پارامترهای پُرسمان، رفتار متفاوتی دارند. اغلب، کارگزار بخشی از این محتوا را برای استفاده در عبارت شرطی استخراج می‌کند. برای انجام این کار، از خط‌مشی ExtractVariables استفاده کنید.

هنگام تعریف خط‌مشی ExtractVariables، می‌توانید انتخاب کنید:

• نام‌های متغیرهایی که باید تنظیم شوند
• منبع متغیرها
• تعداد متغیرهایی که باید استخراج و تنظیم شود

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

برای دیدن اینکه چگونه می‌توان از ExtractVariables برای ساختن گزارش‌های Analytics محتوا-محور استفاده کرد، به تجزیه‌وتحلیل محتوای پیام API بااستفاده از Analytics سفارشی مراجعه کنید.

حوزه

متغیرهای تنظیم‌شده با خط‌مشی ExtractVariables دارای محدوده جهانی هستند. یعنی پس‌از اینکه خط‌مشی ExtractVariables متغیر جدیدی را تعریف کرد، می‌توانید از هر خط‌مشی یا کدی در هر مرحله از جریان (که پس‌از خط‌مشی ExtractVariables اجرا می‌شود) به آن متغیر دسترسی پیدا کنید. این شامل موارد زیر می‌شود:

• PreFlow: ProxyEndpoint و TargetEndpoint (درخواست و پاسخ)
• PostFlow: ProxyEndpoint و TargetEndpoint (درخواست و پاسخ)
• PostClientFlow: ProxyEndpoint (فقط پاسخ، بااستفاده از خط‌مشی ثبت پیام)
• جریان‌های خطا

درباره مطابقت و ساخت متغیر

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

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

مسیرهای نشانی وب، پارامترهای پُرسمان، سرایندها، پارامترهای فرم، و متغیرهای منطبق

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

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

در این مثال، متغیر urirequest.pathSeg روی هر چیزی که در proxy.pathsuffix بعداز «/a/» ظاهر می‌شود تنظیم شده است. برای مثال، فرض کنید مسیر پایه برای «پراکسی میانای برنامه‌سازی کاربردی» شما /basepath/v1 باشد . با درخواست ورودی به http://myCo.com/basepath/v1/a/b متغیر روی «b» تنظیم می‌شود.

مشخص کردن چندین الگو

می‌توانید چندین الگو را برای مطابقت مشخص کنید که با برچسب‌های <Pattern> مطابقت دارند، در اینجا:

• همه الگوها برای مطابقت آزمایش می‌شوند.
• اگر هیچ‌یک از الگوها مطابقت نداشته باشد، خط‌مشی هیچ کاری انجام نمی‌دهد و متغیر(ها) ایجاد نمی‌شود.
• اگر بیش‌از یک الگو مطابقت داشته باشد، الگویی که طولانی‌ترین بخش‌های مسیر را دارد برای استخراج استفاده می‌شود.
• اگر دو الگوی منطبق دارای بخش‌های طولانی‌ترین مسیر یکسان باشند، الگویی که ابتدا در خط‌مشی مشخص شده است برای استخراج استفاده می‌شود.

در مثال بعدی، خط‌مشی‌ای ایجاد می‌کنید که حاوی سه الگوی تطبیق برای مسیر نشانی وب است:

<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 ، نشانی وب درخواست ورودی به پراکسی میانای برنامه‌سازی کاربردی به این شکل است:

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

در این مثال، الگوی اول با شناسه منبع یکنواخت مطابقت دارد و متغیر urirequest.pathSeg روی «b» تنظیم شده است.

اگر نشانی وب درخواست این باشد:

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 برای درخواست ورودی نشانی وب:

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

برای ارجاع دادن به این پارامترهای پُرسمان در خط‌مشی ExtractVariables، از شاخص‌ها استفاده می‌کنید، درحالی‌که اولین نمونه پارامتر پُرسمان شاخص ندارد، دومین نمونه در شاخص ۲، سومین نمونه در شاخص ۳، و غیره قرار دارد. برای مثال، خط‌مشی زیر مقدار دومین پارامتر پُرسمان به‌نام «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 روی «۲» تنظیم شده است. اگر پارامتر پُرسمان دوم از درخواست حذف شود، متغیر urirequest.secondW خالی است. هرگاه چندین مورد با نام یکسان در درخواست وجود دارد، از نمایه کردن استفاده کنید.

استفاده از نویسه‌های خاص در الگو

هنگام مطابقت دادن مسیرهای نشانی وب، می‌توانید از نویسه‌های عام «*» و «**» در الگو استفاده کنید، در این الگو:

• «*» با هریک از بخش‌های مسیر مطابقت دارد
• ‫«**» با چندین بخش از مسیر مطابقت دارد

برای مثال، الگوهایی را برای عنصر <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/bar» مطابقت دارد.

هنگام مشخص کردن الگوها برای پارامترهای پُرسمان، سرایندها، و پارامترهای فرم، نویسه «*» مشخص می‌کند که با هر تعداد نویسه مطابقت داشته باشد. برای مثال، هنگام مطابقت دادن سرصفحه، الگو را به‌صورت زیر مشخص کنید: pattern as:

*;charset={encoding}

این الگو با مقادیر «text/xml;charset=UTF-16» و «application/xml;charset=ASCII» مطابقت دارد.

اگر مقدار منتقل‌شده به خط‌مشی ExtractVariables حاوی نویسه خاصی مثل «{» باشد، از نویسه «٪» برای فرار از آن استفاده کنید. در مثال زیر، نویسه‌های «{» و «}» در الگو گریز داده می‌شوند زیرا به‌عنوان نویسه‌های حرفی در مقدار پارامتر پُرسمان استفاده می‌شوند:

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

در این مثال، الگو با مقدار «{user} Steve» مطابقت دارد اما با مقدار «user Steve» مطابقت ندارد.

تطبیق JSON و XML

هنگام استخراج داده‌ها از JSON و XML، یک یا چند برچسب <Variable> را در خط‌مشی مشخص می‌کنید. برچسب <Variable> نام متغیر مقصد را که اطلاعات استخراج‌شده در آن ذخیره می‌شود و JsonPath (JSON) یا XPATH (XML) را به اطلاعات استخراج‌شده مشخص می‌کند.

همه برچسب‌های <Variable> در خط‌مشی ارزیابی می‌شوند، بنابراین می‌توانید چندین متغیر را از یک خط‌مشی واحد تکمیل کنید. اگر برچسب <Variable> به فیلد معتبری در JSON یا XML ارزیابی نشود، متغیر مربوطه ایجاد نمی‌شود.

مثال زیر خط‌مشی ExtractVariables را نشان می‌دهد که دو متغیر را از بدنه 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 را توصیف می‌کند.

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

ویژگی‌های <ExtractVariables>

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

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

عنصر <Source>

(اختیاری) متغیری را که باید تجزیه شود مشخص می‌کند. مقدار <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>

برای مثال، فرض کنید مقدار نام «کاربر» باشد.

• اگر <VariablePrefix> مشخص نشده باشد، مقادیر استخراج‌شده به متغیری به‌نام user اختصاص داده می‌شود.
• اگر <VariablePrefix> به‌عنوان پیشوند من مشخص شده باشد، مقادیر استخراج‌شده به متغیری به‌نام myprefix.user اختصاص داده می‌شود.

عنصر <IgnoreUnresolvedVariables>

(اختیاری) برای درنظر گرفتن هر متغیر غیرقابل‌حلی به‌عنوان رشته خالی (تهی)، روی true تنظیم کنید. اگر می‌خواهید وقتی هریک از متغیرهای ارجاع‌داده‌شده قابل‌حل نیست، خط‌مشی خطا ایجاد کند، روی false تنظیم کنید.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

اگر مرجع XPath در <XMLPayload> حل‌نشده باشد، خط‌مشی خطای زیر را برمی‌گرداند:

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

عنصر <URIPath>

(اختیاری، اما برای اطلاعات بیشتر، ردیف «حضور» را در جدول زیر ببینید.) مقدار را از proxy.pathsuffix پیام منبع درخواست استخراج می‌کند. مسیر اعمال‌شده به الگو proxy.pathsuffix است که شامل basepath برای «پراکسی API» نمی‌شود. اگر پیام منبع به نوع پیام پاسخ تبدیل شود، این عنصر هیچ کاری انجام نمی‌دهد.

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

(اختیاری، اما برای اطلاعات بیشتر، ردیف «حضور» را در جدول زیر ببینید.) مقداری را از پارامتر پُرسمان مشخص‌شده پیام منبع درخواست استخراج می‌کند. اگر پیام منبع به نوع پیام پاسخ تبدیل شود، این عنصر هیچ کاری انجام نمی‌دهد.

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

(اختیاری، اما برای اطلاعات بیشتر، ردیف «حضور» را در جدول زیر ببینید.) مقدار را از پارامتر فرم مشخص‌شده پیام درخواست یا پاسخ استخراج می‌کند. پارامترهای فرم فقط زمانی استخراج می‌شود که سرایند 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 فقط زمانی انجام می‌شود که سرایند Content-Type پیام 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>

طرح‌واره‌ها

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

تجزیه‌وتحلیل محتوای پیام «میانای برنامه‌سازی کاربردی» بااستفاده از تجزیه‌وتحلیل سفارشی

مرجع متغیرها