سیاست ExtractVariables

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

چه

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

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

محدوده

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

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

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

سیاست ExtractVariables اطلاعات را از یک درخواست یا پاسخ استخراج می‌کند و آن اطلاعات را در یک متغیر می‌نویسد. برای هر نوع اطلاعاتی که می‌توانید استخراج کنید، مانند مسیر 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 روی هر چیزی که در proxy.pathsuffix بعد از "/a/" ظاهر می‌شود، تنظیم می‌شود. برای مثال، فرض کنید مسیر پایه برای API Proxy شما /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>

فرض کنید، برای یک پروکسی API با مسیر پایه /basepath/v1 ، آدرس اینترنتی درخواست ورودی به پروکسی API به این شکل است:

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

در این مثال، الگوی اول با URI مطابقت دارد و متغیر 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>

دوباره فرض کنید یک API Proxy با مسیر پایه /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

برای ارجاع به این پارامترهای پرس‌وجو در سیاست 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 روی "2" تنظیم شده است. اگر پارامتر دوم کوئری از درخواست حذف شود، متغیر urirequest.secondW خالی خواهد بود. هر زمان که چندین آیتم با نام یکسان در درخواست وجود داشته باشد، از اندیس‌گذاری استفاده کنید.

استفاده از کاراکترهای ویژه در الگو

هنگام تطبیق مسیرهای URI، می‌توانید از کاراکترهای wildcard "*" و "**" در الگو استفاده کنید، که در آن:

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

برای مثال، شما الگوها را به عنصر <URIPath> مانند زیر مشخص می‌کنید:

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

الگوی اول درخواست‌هایی را که پسوند مسیر (بخشی از مسیر URI که پس از مسیر پایه قرار می‌گیرد) دارند، مانند "/a/b/c"، "/a/foo/bar" و غیره، مطابقت می‌دهد. الگوی دوم هر تعداد از بخش‌های مسیر بعد از "/a/" را مطابقت می‌دهد، مانند "/a/foo/bar/baz/c" و همچنین "/a/b/c" و "/a/foo/bar".

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

*;charset={رمزگذاری}

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

اگر مقداری که به سیاست ExtractVariables ارسال می‌شود حاوی یک کاراکتر خاص مانند "{" باشد، از کاراکتر "%" برای escape کردن آن استفاده کنید. مثال زیر کاراکترهای "{" و "}" را در الگو escape می‌کند زیرا آنها به عنوان کاراکترهای تحت‌اللفظی در مقدار پارامتر پرس‌وجو استفاده می‌شوند:

<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> در سیاستی که به متغیر ارجاع می‌دهد، روی true تنظیم کنید تا سیاست را طوری پیکربندی کنید که با هر متغیر غیرقابل حل به عنوان یک رشته خالی (null) رفتار کند:

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

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

اگر <Source> قابل حل نباشد، یا به نوع غیرپیام حل شود، این خط‌مشی پاسخی نخواهد داد.

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

ویژگی‌ها

عنصر <VariablePrefix>

(اختیاری) نام کامل متغیر با اتصال <VariablePrefix> ، یک نقطه، و نامی که در داخل {} در عنصر <Pattern> یا عنصر <Variable> تعریف می‌کنید، ایجاد می‌شود. برای مثال: myprefix.id ، myprefix.dbncode یا myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

برای مثال، فرض کنید مقدار name برابر با "user" باشد.

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

عنصر <نادیده گرفتن متغیرهای حل نشده>

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

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

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

عنصر <URIPath>

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

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

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

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

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

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

ویژگی‌ها

عنصر <سربرگ>

(اختیاری است، اما برای اطلاعات بیشتر به ردیف Presence در جدول زیر مراجعه کنید.) مقداری را از هدر 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>

(اختیاری است، اما برای اطلاعات بیشتر به ردیف Presence در جدول زیر مراجعه کنید.) مقداری را از پارامتر فرم مشخص شده از پیام درخواست یا پاسخ مشخص شده استخراج می‌کند. پارامترهای فرم فقط زمانی قابل استخراج هستند که سربرگ Content-Type پیام مشخص شده application/x-www-form-urlencoded باشد.

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

ویژگی‌ها

عنصر <متغیر>

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

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

برای استخراج دو مقدار از متغیر:

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

ویژگی‌ها

عنصر <JSONPayload>

(اختیاری است، اما برای اطلاعات بیشتر به ردیف Presence در جدول زیر مراجعه کنید.) پیام با فرمت 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>

(اختیاری است، اما برای اطلاعات بیشتر به ردیف Presence در جدول زیر مراجعه کنید.) پیام با فرمت 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>

مرجع خطا

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

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

طرحواره‌ها

مباحث مرتبط

تجزیه و تحلیل محتوای پیام API با استفاده از تجزیه و تحلیل‌های سفارشی

مرجع متغیرها