خط مشی ServiceCallout

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

چه

سیاست فراخوانی سرویس به شما امکان می‌دهد از جریان پروکسی API خود به سرویس دیگری فراخوانی کنید. می‌توانید فراخوانی‌ها را به یک سرویس خارجی (مانند یک نقطه پایانی سرویس RESTful خارجی) یا سرویس‌های داخلی (مانند یک پروکسی API در همان سازمان و محیط) انجام دهید.

• در یک مورد استفاده خارجی، شما فراخوانی را به یک API شخص ثالث که خارج از پروکسی شما است، ارسال می‌کنید. پاسخ از API شخص ثالث تجزیه و در پیام پاسخ API شما درج می‌شود و داده‌ها را برای کاربران نهایی برنامه غنی‌سازی و "ترکیب" می‌کند. همچنین می‌توانید با استفاده از خط‌مشی فراخوانی سرویس در جریان درخواست، درخواستی ارسال کنید، سپس اطلاعات موجود در پاسخ را به TargetEndpoint پروکسی API ارسال کنید.
• در یک مورد استفاده دیگر، شما یک پروکسی را فراخوانی می‌کنید که در همان سازمان و محیطی است که از آن فراخوانی می‌کنید. به عنوان مثال، ممکن است این مورد زمانی مفید باشد که یک پروکسی دارید که برخی از عملکردهای سطح پایین گسسته را ارائه می‌دهد که یک یا چند پروکسی دیگر از آن استفاده می‌کنند. به عنوان مثال، یک پروکسی که عملیات ایجاد/خواندن/به‌روزرسانی/حذف را با یک فروشگاه داده backend در معرض نمایش قرار می‌دهد، می‌تواند پروکسی هدف برای چندین پروکسی دیگر باشد که داده‌ها را در اختیار کلاینت‌ها قرار می‌دهند.

این خط‌مشی از درخواست‌های HTTP و HTTPS پشتیبانی می‌کند.

نمونه‌ها

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

درباره سیاست فراخوان خدمات

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

یک فراخوانی معمولاً با دو سیاست دیگر استفاده می‌شود: اختصاص پیام و استخراج متغیرها.

• درخواست : پیام اختصاص، پیام درخواست ارسال شده به سرویس راه دور را پر می‌کند.

• پاسخ : استخراج متغیرها، پاسخ را تجزیه و تحلیل کرده و محتوای خاص را استخراج می‌کند.

ترکیب معمول سیاست فراخوانی خدمات شامل موارد زیر است:

1. سیاست اختصاص پیام : یک پیام درخواست ایجاد می‌کند، هدرهای HTTP، پارامترهای پرس‌وجو را پر می‌کند، فعل HTTP را تنظیم می‌کند و غیره.
2. سیاست فراخوانی سرویس : به پیامی که توسط سیاست اختصاص پیام ایجاد شده است اشاره می‌کند، یک URL هدف برای فراخوانی خارجی تعریف می‌کند و نامی را برای شیء پاسخی که سرویس هدف برمی‌گرداند، تعریف می‌کند.
   
   برای بهبود عملکرد، می‌توانید پاسخ‌های Service Callout را نیز ذخیره کنید، همانطور که در این تاپیک انجمن Apigee توضیح داده شده است: چگونه می‌توانم نتایج سیاست ServiceCallout را در حافظه پنهان ذخیره کنم و بعداً آن را از حافظه پنهان بازیابی کنم؟
3. سیاست استخراج متغیرها : معمولاً یک عبارت JSONPath یا XPath تعریف می‌کند که پیام تولید شده توسط Service Callout را تجزیه می‌کند. سپس این سیاست متغیرهایی را تنظیم می‌کند که حاوی مقادیر تجزیه شده از پاسخ Service Callout هستند.

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

مدیریت خطای سفارشی

مرجع عنصر

در زیر عناصر و ویژگی‌هایی که می‌توانید در این سیاست پیکربندی کنید، آمده است:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

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

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

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

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

عنصر <درخواست>

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

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

نحو (syntax) تگ‌های <Remove> ، <Copy> ، <Add> و <Set> همانند سیاست Assign Message است.

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

در ساده‌ترین مثال، شما یک متغیر حاوی پیام درخواستی که قبلاً در جریان پروکسی API پر شده است، ارسال می‌کنید:

<Request clearPayload="true" variable="myRequest"/>

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

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

ویژگی‌ها

عنصر <Request>/<IgnoreUnresolvedVariables>

وقتی روی true تنظیم شود، این خط‌مشی هرگونه خطای متغیر حل‌نشده در درخواست را نادیده می‌گیرد.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

عنصر <پاسخ>

این عنصر را زمانی اضافه کنید که منطق پروکسی API برای پردازش بیشتر به پاسخ فراخوانی از راه دور نیاز داشته باشد.

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

اگر این عنصر حذف شود، پروکسی API منتظر پاسخ نمی‌ماند؛ اجرای جریان پروکسی API با هر مرحله بعدی جریان ادامه می‌یابد. همچنین، برای روشن شدن موضوع، بدون عنصر Response ، پاسخ از هدف برای پردازش توسط مراحل بعدی در دسترس نیست و هیچ راهی برای جریان پروکسی وجود ندارد که بتواند خرابی در فراخوانی از راه دور را تشخیص دهد. یک کاربرد رایج برای حذف عنصر Response هنگام استفاده از ServiceCallout: ثبت پیام‌ها به یک سیستم خارجی.

 <Response>calloutResponse</Response>

عنصر <Timeout>

مدت زمانی که سیاست فراخوانی سرویس (Service Callout) منتظر پاسخ از هدف می‌ماند (به میلی‌ثانیه). شما نمی‌توانید این مقدار را به صورت پویا در زمان اجرا تنظیم کنید. اگر فراخوانی سرویس به زمان انقضا برسد، یک HTTP 500 برگردانده می‌شود، سیاست با شکست مواجه می‌شود و پروکسی API وارد حالت خطا می‌شود، همانطور که در بخش مدیریت خطاها توضیح داده شده است.

<Timeout>30000</Timeout>

عنصر <HTTPTargetConnection>

جزئیات انتقال مانند ویژگی‌های URL، TLS/SSL و HTTP را ارائه می‌دهد. به مرجع پیکربندی <TargetEndpoint> مراجعه کنید.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

عنصر <HTTPTargetConnection>/<URL>

آدرس اینترنتی (URL) سرویسی که فراخوانی می‌شود:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

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

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

یا، بخشی از مسیر URL را با یک متغیر تنظیم کنید:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

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

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

عنصر <HTTPTargetConnection>/<SSLInfo>

پیکربندی TLS/SSL برای سرویس backend. برای راهنمایی در مورد پیکربندی TLS/SSL، به پیکربندی TLS از Edge به backend (Cloud و Private Cloud) و "پیکربندی TLS/SSL TargetEndpoint" در مرجع پیکربندی پروکسی API مراجعه کنید.