سياسة وسيلة الشرح

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

المزايا

تتيح لك سياسة "وسيلة شرح الخدمة" الاتصال بخدمة أخرى من مسار الخادم الوكيل لواجهة برمجة التطبيقات. إِنْتَ إنشاء وسائل شرح لخدمة خارجية (مثل نقطة نهاية خدمة RESTful خارجية) أو خدمات داخلية (مثل خادم وكيل لواجهة برمجة التطبيقات في نفس المؤسسة والبيئة).

• في حالة استخدام خارجية، يمكنك توفير وسيلة شرح لواجهة برمجة تطبيقات تابعة لجهة خارجية تكون خارجة عن الخادم الوكيل. يتم تحليل الردّ من واجهة برمجة التطبيقات التابعة لجهة خارجية وإدراجه في ردّ واجهة برمجة التطبيقات. الرسائل، وإثراء و"دمج" بيانات المستخدمين النهائيين للتطبيق. يمكنك أيضًا تقديم طلب استخدام سياسة وسيلة شرح الخدمة في مسار الطلب، ثم تمرير المعلومات في الردّ إلى نقطة النهاية المستهدفة للخادم الوكيل لواجهة برمجة التطبيقات.
• وفي حالة استخدام أخرى، يمكنك استدعاء خادم وكيل موجود في نفس المؤسسة والبيئة مثل الذي تتصل منه. على سبيل المثال، قد تجد هذا مفيدًا عندما يكون لديك خادم وكيل توفر بعض الوظائف المنفصلة منخفضة المستوى التي سيستهلكها خادم وكيل آخر أو أكثر. بالنسبة خادم وكيل يكشف عن عمليات الإنشاء/القراءة/التحديث/الحذف باستخدام مخزن بيانات في الخلفية هو الوكيل المستهدف للعديد من الخوادم الوكيلة الأخرى التي تعرض البيانات للعملاء.

تتوافق السياسة مع الطلبات عبر 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>

لمحة عن سياسة وسائل شرح الخدمة

هناك العديد من السيناريوهات التي يمكنك فيها استخدام سياسة وسيلة شرح الخدمة في الخادم الوكيل لواجهة برمجة التطبيقات. بالنسبة يمكنك، مثلاً، ضبط خادم وكيل لواجهة برمجة التطبيقات لإجراء اتصالات بخدمة خارجية من أجل تسليم بيانات الموقع الجغرافي ومراجعات العملاء والسلع من كتالوج البيع بالتجزئة الخاص بالشريك وما إلى ذلك

تُستخدم وسيلة الشرح عادةً مع سياستين أخريين: تعيين متغيري الرسالة واستخراج البيانات.

• الطلب: يؤدي ضبط رسالة إلى تعبئة رسالة الطلب المُرسَلة إلى جهاز التحكّم عن بُعد. خدمة ما.

• الرد: تعمل متغيرات استخراج البيانات على تحليل الرد واستخلاص بيانات محددة المحتوى.

تشمل تركيبة سياسة "وسائل شرح الخدمة" النموذجية ما يلي:

1. تعيين رسالة السياسة: تنشئ رسالة طلب، وتعبئ عناوين HTTP، ومعلَمات طلب البحث، وتضبط بروتوكول HTTP. والأفعال وما إلى ذلك
2. سياسة وسيلة شرح الخدمة: تشير إلى رسالة تم إنشاؤها بواسطة رسالة تخصيص. وتحدد عنوان URL المستهدف للاستدعاء الخارجي وتحدد اسمًا لكائن الاستجابة التي تعرضها الخدمة المستهدفة.
   
   لتحسين الأداء، يمكنك أيضًا تخزين استجابات وسيلة شرح الخدمة مؤقتًا، كما هو موضح في هذا سلسلة محادثات منتدى Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. استخراج المتغيرات السياسة: تحدد عادةً تعبير JSONPath أو XPath الذي يحلّل الرسالة التي تم إنشاؤها. من خلال وسيلة شرح الخدمة. تُحدِّد السياسة بعد ذلك المتغيّرات التي تحتوي على القيم التي تم تحليلها من استجابة وسيلة شرح الخدمة.

راجع استخدام السياسة التكوين لنموذج كامل من وكيل واجهة برمجة التطبيقات الذي يستخدم سياسة وسيلة شرح الخدمة إلى جانب سياستَي "تعيين الرسائل واستخراج المتغيرات"

معالجة مخصصة للأخطاء

مرجع العنصر

في ما يلي العناصر والسمات التي يمكنك ضبطها في هذه السياسة:

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

تُحدِّد المتغيّر الذي يحتوي على رسالة الطلب التي يتم إرسالها من الخادم الوكيل لواجهة برمجة التطبيقات إلى خدمة أخرى. يمكن إنشاء المتغير من خلال سياسة سابقة في التدفق، أو يمكنك إنشائه. مضمّن في سياسة وسائل شرح الخدمة.

<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> مع بنية العلامة تعيين رسالة .

تعرض السياسة رسالة خطأ إذا تعذر حل رسالة الطلب أو إذا كانت رسالة الطلب غير صالحة نوع رسالة الطلب.

في أبسط مثال، يمكنك تمرير متغير يحتوي على رسالة الطلب التي تمت تعبئتها سابقًا في مسار الخادم الوكيل لواجهة برمجة التطبيقات:

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

السمات

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; عنصر

وعند ضبطها على true، تسري السياسة أي خطأ متغير لم يتم حله في الطلب.

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

&lt;Response&gt; عنصر

يتم تضمين هذا العنصر عندما يتطلب منطق الخادم الوكيل لواجهة برمجة التطبيقات الحصول على استجابة من استدعاء البيانات عن بُعد ومعالجة إضافية لها.

عند وجود هذا العنصر، فإنه يحدد اسم المتغير الذي سيحتوي على رسالة استجابة تم استلامها من الخدمة الخارجية. يتم تعيين الاستجابة من الهدف إلى المتغير فقط عندما تقرأ السياسة الاستجابة كاملةً بنجاح. إذا كانت المكالمة عن بُعد لأي سبب من الأسباب، تعرض السياسة خطأً.

في حال إسقاط هذا العنصر، لن ينتظر الخادم الوكيل لواجهة برمجة التطبيقات تلقّي ردّ. مسار الخادم الوكيل لواجهة برمجة التطبيقات والتنفيذ مع أي خطوات تدفق لاحقة. أيضًا، لتوضيح ما هو واضح، بدون Response، فإن الاستجابة من الهدف غير متاحة للمعالجة من خلال الخطوات اللاحقة، ولا تتوفر طريقة لتدفق الخادم الوكيل لرصد عطل في المكالمة عن بُعد. استخدام شائع لحذف العنصر Response عند استخدام ServiceCallout: لتسجيل الرسائل إلى نظام خارجي.

 <Response>calloutResponse</Response> 

<المهلة> عنصر

الوقت بالملي ثانية الذي ستنتظر فيه سياسة وسيلة شرح الخدمة تلقّي ردّ من الهدف. ولا يمكنك ضبط هذه القيمة ديناميكيًا في وقت التشغيل. إذا انتهت مهلة وسيلة شرح الخدمة، يتم عرض HTTP 500، وتفشل السياسة، وينتقل الخادم الوكيل لواجهة برمجة التطبيقات إلى حالة خطأ، الموضحة في مقالة معالجة الأخطاء.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; عنصر

توفر تفاصيل النقل مثل خصائص HTTP وطبقة النقل الآمنة (TLS)/طبقة المقابس الآمنة (SSL). يمكنك الاطّلاع على مرجع إعداد <TargetEndpoint>.

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; عنصر

عنوان 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>

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; عنصر

ضبط بروتوكول أمان طبقة النقل (TLS)/طبقة المقابس الآمنة (SSL) لخدمة الخلفية للحصول على مساعدة بشأن إعداد TLS/SSL، يمكنك الاطّلاع على تهيئة بروتوكول أمان طبقة النقل (TLS) من Edge إلى الخلفية (Cloud and Private Cloud) و"ضبط نقطة النهاية لطبقة النقل الآمنة/طبقة المقابس الآمنة" في مرجع إعداد الخادم الوكيل لواجهة برمجة التطبيقات.

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

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; عنصر

يمكنك استدعاء خادم هدف واحد أو أكثر وإجراء موازنة الحمل عليه. الاطّلاع على هدف المكالمات الخوادم في قسم "عيّنات". يمكنك الاطّلاع أيضًا على موازنة التحميل في الخلفية. الخوادم. اطّلع أيضًا على هذا المنتدى مشاركة تناقش طرق الاتصال بالخوادم المستهدفة من سياسة وسيلة شرح الخدمة باستخدام قواعد المسار.

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

&lt;LocalTargetConnection&gt; عنصر

تُحدد خادمًا وكيلاً محليًا -- أي وكيل في نفس المؤسسة والبيئة -- مثل الهدف من وسائل شرح الخدمة.

لتحديد الهدف بشكل أكبر، استخدِم إما العنصرَين <APIProxy> و<ProxyEndpoint> أو العنصر <Path>.

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

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; عنصر

اسم الخادم الوكيل لواجهة برمجة التطبيقات المستهدف في استدعاء محلي. يجب أن يكون الخادم الوكيل في نفس المؤسسة والبيئة كخادم وكيل يجري الاتصال.

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

إلى جانب العنصر <APIProxy>، ضمِّن السمة <ProxyEndpoint> لتحديد اسم نقطة نهاية الخادم الوكيل أن تكون مستهدفًا للمكالمة.

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

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; عنصر

اسم نقطة نهاية الخادم الوكيل التي يجب أن تكون هدفًا لعمليات الاستدعاء. هذه هي نقطة نهاية الخادم الوكيل في الخادم الوكيل لواجهة برمجة التطبيقات المحدد بالعنصر <APIProxy>.

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; عنصر

مسار إلى نقطة النهاية التي يتم استهدافها. يجب أن تشير نقطة النهاية إلى وكيل في نفس المؤسسة والبيئة كخادم وكيل يجري الاتصال.

يمكنك استخدام هذا الوضع بدلاً من زوج <APIProxy>/<ProxyEndpoint> في حال عدم استخدام تعرف - أو لا يمكنك الاعتماد - على اسم الخادم الوكيل. فقد يكون المسار هدفًا موثوقًا به.

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

المخططات

متغيّرات التدفق

تعمل متغيرات التدفق على تمكين السلوك الديناميكي للسياسات والتدفقات في وقت التشغيل، بناءً على HTTP العناوين أو محتوى الرسالة أو سياق التدفق. تتوفّر متغيّرات التدفق المحدَّدة مسبقًا التالية بعد تنفيذ سياسة وسيلة شرح الخدمة. لمزيد من المعلومات حول متغيّرات التدفق، اطّلِع على مرجع المتغيرات.

وسائل شرح الخدمة لها طلبات وردود خاصة بها، ويمكنك الوصول إلى هذه البيانات من خلال المتغيرات. نظرًا لأن الرسالة الرئيسية تستخدم request.* بادئات المتغير response.*، استخدم myrequest.* calloutResponse.* بادئات (الإعدادات التلقائية في ضبط وسيلة شرح الخدمة) إلى الحصول على بيانات الرسائل الخاصة بوسيلة شرح الخدمة. يوضح المثال الأول في الجدول التالي كيفية الحصول على رؤوس HTTP في وسيلة شرح الخدمة.

الأخطاء

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 a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

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

مواضيع ذات صلة

• إنشاء الرسائل أو تعديلها: تخصيص سياسة الرسائل
• استخراج المتغيّرات: استخراج المتغيرات السياسة
• المتغيرات: المتغيرات المرجع
• إعداد بروتوكول أمان طبقة النقل (TLS)/طبقة المقابس الآمنة
  • التهيئة بروتوكول أمان طبقة النقل (TLS) من Edge إلى الخلفية (السحابة الإلكترونية والسحابة الإلكترونية الخاصة)
  • "إعداد نقطة النهاية لطبقة النقل الآمنة/طبقة المقابس الآمنة" في مرجع إعداد الخادم الوكيل لواجهة برمجة التطبيقات
• خصائص نقل HTTP: مرجع خصائص نقطة النهاية
• بديل وسيلة شرح الخدمة: HTTPClient مكتوب في JavaScript، راجع نموذج عنصر JavaScript