خط مشی ServiceCallout

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

چی

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

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

این خط‌مشی از درخواست‌های 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>

درباره خط مشی Callout خدمات

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

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

• درخواست : Assign Message پیام درخواست ارسال شده به سرویس راه دور را پر می کند.

• Response : Extract Variables پاسخ را تجزیه و محتوای خاصی را استخراج می کند.

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

1. تعیین خط مشی پیام : یک پیام درخواست ایجاد می کند، سرصفحه های HTTP، پارامترهای پرس و جو را پر می کند، فعل HTTP و غیره را تنظیم می کند.
2. خط مشی Callout Service : به پیام ایجاد شده توسط خط مشی Assign Message ارجاع می دهد، یک URL هدف برای تماس خارجی تعریف می کند و یک نام برای شی پاسخی که سرویس هدف برمی گرداند، تعریف می کند.
   
   برای بهبود عملکرد، می‌توانید پاسخ‌های Service Callout را نیز در حافظه پنهان ذخیره کنید، همانطور که در این رشته انجمن Apigee توضیح داده شده است: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the- servicecallout.html .
3. Extract Variables Policy : معمولاً عبارت JSONPath یا XPath را تعریف می کند که پیام تولید شده توسط Service Callout را تجزیه می کند. سپس این خط مشی متغیرهایی را شامل مقادیر تجزیه شده از پاسخ سرویس Callout تنظیم می کند.

به استفاده از ترکیب خط مشی برای یک نمونه کامل پراکسی API که از خط مشی Callout سرویس همراه با خط مشی های Assign Message and Extract Variables استفاده می کند، مراجعه کنید.

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

مرجع عنصر

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

<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 به سرویس دیگر ارسال می شود را مشخص می کند. متغیر را می توان توسط یک خط مشی قبلی در جریان ایجاد کرد، یا می توانید آن را به صورت درون خطی در خط مشی Service Callout ایجاد کنید.

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

نحو تگ‌های <Remove> ، <Copy> ، <Add> و <Set> مانند خط مشی Assign Message است.

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

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

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

یا می توانید پیام درخواست ارسال شده به سرویس خارجی را در خود خط مشی Callout Service پر کنید:

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

عنصر <Response>

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

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

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

 <Response>calloutResponse</Response> 

عنصر <Timeout>

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

<Timeout>30000</Timeout>

عنصر <HTTPTargetConnection>

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

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

عنصر <HTTPTargetConnection>/<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>/<SSLIinfo>

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