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

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

الموضوع

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

• في حالة الاستخدام الخارجي، يمكنك إنشاء وسيلة شرح لواجهة برمجة تطبيقات تابعة لجهة خارجية وهي خارج الخادم الوكيل. يتم تحليل الردّ من واجهة برمجة التطبيقات التابعة لجهة خارجية وإدراجه في رسالة الردّ الخاصة بواجهة برمجة التطبيقات، ما يحسّن بيانات مستخدمي التطبيق ويدمجها. يمكنك أيضًا تقديم طلب باستخدام سياسة "وسيلة شرح الخدمة" في مسار الطلب، ثم تمرير المعلومات الواردة في الاستجابة إلى 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>

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

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

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

• الطلب: يؤدي تعيين الرسالة إلى تعبئة رسالة الطلب المرسلة إلى الخدمة البعيدة.

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

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

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 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>/<تجاهلUnresolvedVariables>

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

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

عنصر <Response>

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

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

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

 <Response>calloutResponse</Response> 

عنصر <Timeout>

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

<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 أو محتوى الرسالة أو سياق التدفق. تتوفر متغيرات التدفق المحددة مسبقًا التالية بعد تنفيذ سياسة وسيلة شرح الخدمة. لمزيد من المعلومات عن متغيّرات التدفق، يُرجى الاطّلاع على مرجع المتغيرات.

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