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

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

الأدوات المستخدمة

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

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

تتيح السياسة إرسال الطلبات عبر 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 عادةً مع سياستين أخريين: "تعيين رسالة" و"استخراج المتغيرات".

• الطلب: تملأ عملية "تعيين الرسالة" رسالة الطلب التي يتم إرسالها إلى الخدمة البعيدة.

• الردّ: تحلّل ميزة "استخراج المتغيّرات" الردّ وتستخرج محتوًى معيّنًا.

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

1. سياسة "تحديد رسالة": تنشئ رسالة طلب وتملأ عناوين HTTP ومَعلمات الطلب وتضبط فعل HTTP وما إلى ذلك.
2. سياسة استدعاء الخدمة: تشير إلى رسالة تم إنشاؤها بواسطة سياسة "تحديد الرسالة"، وتحدّد عنوان URL مستهدفًا للمكالمة الخارجية، وتحدّد اسمًا لعنصر الرد الذي تعرضه الخدمة المستهدَفة.
   
   لتحسين الأداء، يمكنك أيضًا تخزين ردود Service Callout مؤقتًا، كما هو موضّح في سلسلة المحادثات التالية في "منتدى Apigee": كيف يمكنني تخزين نتائج سياسة ServiceCallout مؤقتًا واستردادها لاحقًا من ذاكرة التخزين المؤقت؟.
3. سياسة استخراج المتغيرات: تحدّد عادةً تعبير JSONPath أو XPath يحلّل الرسالة التي تم إنشاؤها بواسطة Service Callout. تضبط السياسة بعد ذلك متغيّرات تحتوي على القيم التي تم تحليلها من استجابة Service Callout.

راجِع مقالة استخدام تركيبة السياسات للحصول على نموذج كامل لخادم وكيل لواجهة برمجة التطبيقات يستخدم سياسة "استدعاء الخدمة" مع سياستَي "تعيين الرسالة" و"استخراج المتغيرات".

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

مرجع العنصر

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

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

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة name لتصنيف السياسة في إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

العنصر <Request>

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

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

السمات

العنصر <Request>/<IgnoreUnresolvedVariables>

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

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

العنصر <Response>

أدرِج هذا العنصر عندما يتطلّب منطق خادم وكيل واجهة برمجة التطبيقات الردّ من الاتصال البعيد لإجراء المزيد من المعالجة.

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

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

 <Response>calloutResponse</Response>

العنصر <Timeout>

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

<Timeout>30000</Timeout>

عنصر <HTTPTargetConnection>

توفّر تفاصيل النقل، مثل عنوان URL وبروتوكول أمان طبقة النقل/طبقة المقابس الآمنة وخصائص 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 للخدمة الخلفية للحصول على مساعدة بشأن إعدادات TLS/SSL، يُرجى الاطّلاع على إعداد بروتوكول أمان طبقة النقل (TLS) من Edge إلى الخلفية (السحابة الإلكترونية والسحابة الإلكترونية الخاصة) و "إعدادات TargetEndpoint لبروتوكول أمان طبقة النقل (TLS)/طبقة المقابس الآمنة (SSL)" في مرجع إعدادات خادم وكيل واجهة برمجة التطبيقات.

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

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

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

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

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

العنصر <LocalTargetConnection>/<ProxyEndpoint>

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

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

العنصر <LocalTargetConnection>/<Path>

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

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

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

المخططات

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

تتيح متغيرات التدفق سلوكًا ديناميكيًا للسياسات وعمليات التدفق في وقت التشغيل، استنادًا إلى عناوين HTTP أو محتوى الرسالة أو سياق التدفق. تتوفّر متغيرات Flow المحدّدة مسبقًا التالية بعد تنفيذ سياسة Service Callout. لمزيد من المعلومات عن متغيرات Flow، يُرجى الاطّلاع على مرجع المتغيرات.

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

الأخطاء

يصف هذا القسم رموز الخطأ ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تم ضبطها من خلال 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
  • ضبط إعدادات بروتوكول أمان طبقة النقل (TLS) من Edge إلى الخلفية (السحابة الإلكترونية والسحابة الإلكترونية الخاصة)
  • "إعدادات TargetEndpoint لبروتوكول أمان طبقة النقل/طبقة المقابس الآمنة" في مرجع إعدادات خادم وكيل واجهة برمجة التطبيقات
• سمات نقل البيانات عبر HTTP: مرجع سمات نقطة النهاية
• بديل لـ Service Callout: HTTPClient مكتوب بلغة JavaScript، راجِع نموذج كائن JavaScript