خط‌مشی ServiceCallout

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

چه

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

• در مورد استفاده خارجی، با یک میانای برنامه‌سازی کاربردی طرف سوم که خارج از پراکسی شما است تماس می‌گیرید. پاسخ از API شخص ثالث تجزیه و در پیام پاسخ API شما درج می‌شود و داده‌ها را برای کاربران نهایی برنامه غنی‌سازی و ترکیب می‌کند. همچنین می‌توانید در جریان درخواست، بااستفاده از خط‌مشی «نوشته راهنمای سرویس» درخواست کنید، سپس اطلاعات را در پاسخ به «نقطه پایانی هدف» کارگزار 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>

درباره خط‌مشی «نوشتار راهنمای خدمات»

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

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

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

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

ترکیب خط‌مشی «نوشتار راهنمای تماس با سرویس» معمولاً شامل موارد زیر است:

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

برای نمونه کامل کارگزار 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>

عنصر <Request>

متغیری را که حاوی پیام درخواستی است که از پراکسی 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>

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

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

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

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

عنصر <Response>

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

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

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

 <Response>calloutResponse</Response>

عنصر <Timeout>

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

<Timeout>30000</Timeout>

عنصر <HTTPTargetConnection>

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

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

عنصر <HTTPTargetConnection>/<URL>

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

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

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

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

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

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

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

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

عنصر <HTTPTargetConnection>/<SSLInfo>

پیکربندی «امنیت لایه انتقال»/ پوسته ایمن برای سرویس زیرینه. برای دریافت راهنمایی درباره پیکربندی «امنیت لایه انتقال»/ SSL، به پیکربندی «امنیت لایه انتقال» از Edge تا زیرینه (Cloud و Private Cloud) و «پیکربندی TargetEndpoint «امنیت لایه انتقال»/ SSL» در مرجع پیکربندی پراکسی API مراجعه کنید.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>

ویژگی‌های انتقال HTTP به سرویس زیرینه. برای اطلاعات بیشتر، به مرجع ویژگی‌های نقطه پایانی مراجعه کنید.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>

عنصر <HTTPTargetConnection>/<LoadBalancer>

با یک یا چند سرور هدف تماس می‌گیرد و تراز بار را روی آن‌ها انجام می‌دهد. نمونه سرورهای هدف تماس را در بخش نمونه‌ها ببینید. همچنین تراز کردن بار در سرورهای زیرینه را ببینید. همچنین این پست انجمن را ببینید که درباره روش‌های تماس با سرورهای هدف از هر دو خط‌مشی «پیام‌واره تماس با سرویس» و بااستفاده از «قوانین مسیر» بحث می‌کند.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

عنصر <LocalTargetConnection>

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

برای مشخص کردن بیشتر هدف، از عناصر <APIProxy> و <ProxyEndpoint> یا عنصر <Path> استفاده کنید.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

عنصر <LocalTargetConnection>/<APIProxy>

نام یک پراکسی API که هدف یک تماس محلی است. کارگزار باید در همان سازمان و محیط کارگزار تماس‌گیرنده باشد.

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

علاوه‌بر عنصر <APIProxy>، عنصر <ProxyEndpoint> را نیز اضافه کنید تا نام نقطه پایانی پراکسی را که باید برای تماس هدف‌یابی شود مشخص کنید.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>

عنصر <LocalTargetConnection>/<ProxyEndpoint>

نام نقطه پایانی پراکسی که باید هدف تماس‌ها باشد. این یک نقطه پایانی پراکسی در پراکسی API است که با عنصر <APIProxy> مشخص شده است.

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

عنصر <LocalTargetConnection>/<Path>

مسیر نقطه پایانی که هدف‌یابی می‌شود. نقطه پایانی باید به پراکسی در همان سازمان و محیط پراکسی که تماس را برقرار می‌کند ارجاع دهد.

وقتی نام کارگزار را نمی‌دانید یا نمی‌توانید به آن اعتماد کنید، به‌جای جفت <APIProxy>/<ProxyEndpoint> از این استفاده کنید. این مسیر ممکن است هدف قابل‌اعتمادی باشد.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

طرح‌واره‌ها

متغیرهای جریان

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

«نوشته‌های راهنمای خدمات» درخواست و پاسخ خودشان را دارند و می‌توانید ازطریق متغیرها به آن داده‌ها دسترسی پیدا کنید. چون پیام اصلی از پیشوندهای متغیر request.* و response.* استفاده می‌کند، از پیشوندهای myrequest.* و calloutResponse.* (پیش‌فرض‌های پیکربندی «نوشته راهنمای سرویس») برای دریافت داده‌های پیام ویژه «نوشته راهنمای سرویس» استفاده کنید. اولین مثال در جدول زیر نشان می‌دهد چگونه می‌توانید سرایندهای HTTP را در «تماس با سرویس» دریافت کنید.

خطاها

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

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای خط‌مشی رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می‌شوند که خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدرا ببینید.

نمونه پاسخ خطا

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

قانون خطای نمونه

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

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

• تولید یا اصلاح پیام‌ها: اختصاص دادن خط‌مشی «پیام»
• استخراج متغیرها: استخراج متغیرها خط‌مشی
• متغیرها: متغیرها مرجع
• پیکربندی TLS/SSL
  • پیکربندی «امنیت لایه انتقال» از Edge به زیرینه (Cloud و Private Cloud)
  • «پیکربندی TLS/SSL TargetEndpoint» در مرجع پیکربندی پراکسی API
• خصوصیات انتقال HTTP: مرجع خصوصیات نقطه پایان
• جایگزین «نوشتار راهنمای تماس با خدمات»: HTTPClient نوشته‌شده در جاوا اسکریپت، مدل شیء جاوا اسکریپت را ببینید