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

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

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

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

تتيح لك ميزة معالجة الأخطاء المخصّصة أيضًا إضافة وظائف، مثل تسجيل الرسائل كلما حدث خطأ.

قبل أن نتحدث عن تنفيذ معالجة الأخطاء المخصّصة في خوادم وكيل واجهة برمجة التطبيقات، من المفيد فهم كيفية حدوث الأخطاء وكيفية تفاعل خوادم وكيل واجهة برمجة التطبيقات معها.

الفيديوهات

شاهِد الفيديوهات التالية لمعرفة المزيد عن معالجة الأخطاء.

طريقة حدوث الأخطاء

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

الأخطاء التلقائية

يعرض خادم وكيل لواجهة برمجة التطبيقات خطأ تلقائيًا في الحالات التالية:

• تظهر رسالة خطأ في إحدى السياسات. على سبيل المثال، إذا أرسل طلب بيانات من واجهة برمجة التطبيقات مفتاحًا منتهي الصلاحية، ستعرض سياسة VerifyAPIKey تلقائيًا رسالة خطأ، أو إذا تجاوز عدد طلبات البيانات من واجهة برمجة التطبيقات حدًا معيّنًا، ستعرض سياسة الحصة أو سياسة SpikeArrest رسالة خطأ. (راجِع مرجع أخطاء السياسات للتعرّف على أنواع الأخطاء التي يمكن أن تظهر في السياسات).
• هناك مشكلة في مسار رسائل خادم وكيل واجهة برمجة التطبيقات، مثل خطأ في التوجيه.
• حدث خطأ في الخلفية، مثل خطأ HTTP بسبب أخطاء على مستوى البروتوكول أو أخطاء TLS/SSL أو عدم توفّر الخدمة المستهدَفة.
• حدث عطل على مستوى النظام، مثل استثناء نفاد الذاكرة.

لمزيد من المعلومات عن هذه الأخطاء، اطّلِع على تصنيف الأخطاء في هذا الموضوع.

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

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

يمكنك إضافة سياسة RaiseFault إلى مسار خادم وكيل لواجهة برمجة التطبيقات بالطريقة نفسها التي تضيف بها أي سياسة أخرى. في مثال إعداد الخادم الوكيل التالي، يتم ربط السياسة Raise-Fault-1 باستجابة TargetEndpoint. إذا كانت الكلمة "unavailable" (غير متوفّرة) مضمّنة في الردّ من الخدمة المستهدَفة، سيتم تنفيذ سياسة RaiseFault وعرض خطأ.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

هذا فقط لنوضّح لك أنّه يمكنك عرض أخطاء مخصّصة. يمكنك الاطّلاع على مزيد من التفاصيل حول سياسة RaiseFault في قسم قواعد FaultRules مقابل سياسة RaiseFault.

للاطّلاع على المزيد من الأمثلة، راجِع المشاركات التالية في منتديات Apigee:

• الإشارة إلى متغيّرات JavaScript في RaiseFault

ما تفعله خوادم وكيل واجهة برمجة التطبيقات عند حدوث أخطاء

إليك ما يحدث عندما يعرض الخادم الوكيل خطأً.

الخروج من مسار الخادم الوكيل

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

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

1. التحقّق من مفتاح واجهة برمجة التطبيقات
2. الحصة
3. تحويل JSON إلى XML

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

التحقّق من FaultRules

في حالة الخطأ، تتحقّق خوادم وكيل واجهة برمجة التطبيقات أيضًا من توفّر ما يلي (بالترتيب) في إعدادات خادم وكيل واجهة برمجة التطبيقات قبل عرض رسالة خطأ تلقائية على تطبيق العميل:

1. قسم <FaultRules> يحتوي على منطق لتفعيل رسائل خطأ مخصّصة (وسياسات أخرى) استنادًا إلى شروط محدّدة تحدّدها أنت.
2. قسم <DefaultFaultRule>، الذي يؤدي إلى ظهور رسالة خطأ تلقائية في الحالات التالية:
   • لم يتم تحديد أي <FaultRules>.
   • لا يتم تنفيذ أي <FaultRules> حالية.
   • تم ضبط العنصر <AlwaysEnforce> على "صحيح".

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

مثال بسيط على معالجة الأخطاء

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

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

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

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

في ما يلي مثال أساسي على كيفية إنشاء رسالة خطأ مخصّصة للتعامل مع هذا الخطأ. يتطلّب ذلك 1) سياسة تحدّد الرسالة المخصّصة، و2) FaultRule تنفّذ السياسة عندما يصبح الخادم الوكيل في حالة خطأ.

1. إنشاء سياسة تحدّد الرسالة المخصّصة

أولاً، أنشئ سياسة تحدّد رسالة الخطأ المخصّصة. يمكنك استخدام أي نوع من السياسات، مثل سياسة AssignMessage، التي يمكنها ضبط حمولة وعناوين HTTP اختيارية، مثل رمز الحالة وعبارة السبب. تُعدّ ميزة "تعيين رسالة" مثالية لهذا الغرض. يتيح لك ذلك التحكّم في حمولة الرسالة، وتحديد رمز حالة HTTP مختلف، وتحديد عبارة سبب مختلفة في HTTP، وإضافة عناوين HTTP.

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

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

في ما يلي مثال على سياسة AssignMessage التي:

• تعرض هذه السمة رسالة JSON.
• يضبط هذا الحقل رمز حالة HTTP (911، وهو رمز حالة غير متوفّر بشكل واضح، وذلك فقط لتوضيح المرونة التي يمكنك الاستفادة منها). يظهر رمز الحالة في عنوان HTTP.
• تضبط هذه السمة عبارة سبب HTTP (لاستبدال عبارة السبب التلقائية "غير مصرح به" لخطأ مفتاح واجهة برمجة التطبيقات المفقود هذا). يظهر عبارة السبب بجانب رمز الحالة في عنوان HTTP.
• تنشئ هذه السمة عنوان HTTP جديدًا باسم invalidKey وتملأه.

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

عند تنفيذ هذه السياسة، ستظهر الاستجابة لتطبيق العميل على النحو التالي. قارِنها بالردّ التلقائي الذي تم عرضه سابقًا.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

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

ولكن كيف يتم تنفيذ هذه السياسة؟ يعرض لك القسم التالي ما يلي:

2. إنشاء <FaultRule> الذي سيؤدي إلى تفعيل السياسة

في القسم <ProxyEndpoint> أو <TargetEndpoint> من إعدادات الخادم الوكيل، ستضيفون كتلة <FaultRules> XML تحتوي على قسم واحد أو أكثر من أقسام <FaultRule> الفردية. يمثّل كل FaultRule خطأ مختلفًا تريد معالجته. في هذا المثال البسيط، سنستخدم قاعدة FaultRule واحدة فقط لنوضّح لك مكوناتها.

يجب أيضًا إضافة <DefaultFaultRule> لتقديم رسالة خطأ عامة مخصّصة في حال عدم تنفيذ أي من قواعد FaultRules.

مثال

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

النقاط الرئيسية:

• يتم تحديد FaultRules في ProxyEndpoint. هذا مهم. سنتحدّث لاحقًا عن وضع FaultRules في ProxyEndpoint مقابل TargetEndpoint.
• ‫<Name>: اسم السياسة المطلوب تنفيذها. يتم استخراج الاسم من السمة name الخاصة بالسياسة في العنصر الرئيسي، كما هو موضّح في مثال السياسة أعلاه.

• ‫<Condition>: يقيّم Edge الشرط ولا ينفّذ السياسة إلا إذا كان الشرط صحيحًا. إذا كانت هناك عدّة قواعد FaultRules يتم تقييمها على أنّها صحيحة، ينفّذ Edge القاعدة الأولى التي تكون صحيحة. (ملاحظة مهمة: يختلف ترتيب تقييم FaultRules، من الأعلى إلى الأسفل أو من الأسفل إلى الأعلى، بين TargetEndpoint وProxyEndpoint، كما هو موضّح في قسم قواعد FaultRules المتعددة ومنطق التنفيذ). إذا لم تضمّن شرطًا، سيتم تلقائيًا ضبط قيمة FaultRule على true. لكنّ ذلك ليس من أفضل الممارسات. يجب أن تتضمّن كل FaultRule شرطًا خاصًا بها.

• <DefaultFaultRule>: في حال عدم تنفيذ أي FaultRule مخصّصة، يتم تنفيذ <DefaultFaultRule>، ما يؤدي إلى إرسال رسالة مخصّصة أكثر عمومية بدلاً من الرسالة التلقائية الغامضة التي ينشئها Edge. يمكن أن يتضمّن <DefaultFaultRule> أيضًا <Condition>، ولكن في معظم الحالات، لن تحتاج إلى تضمين <Condition> لأنّك تريد أن يتم تنفيذ <DefaultFaultRule> بغض النظر عن أي شيء كحلّ أخير.

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

قواعد FaultRule متعددة ومنطق التنفيذ

في قسم مثال بسيط على معالجة الأخطاء، استخدمنا مثالاً بسيطًا على FaultRule وشرط واحد. في مشروع حقيقي لواجهة برمجة تطبيقات، ومع كل الأخطاء المحتملة التي يمكن أن تحدث، من المحتمل أن يكون لديك عدة قواعد FaultRule وقاعدة DefaultFaultRule في كل من <ProxyEndpoint> و<TargetEndpoint>. في النهاية، لا يتم تنفيذ سوى قاعدة FaultRule واحدة عندما ينتقل خادم وكيل لواجهة برمجة التطبيقات إلى حالة خطأ.

يوضّح هذا القسم المنطق الذي يستخدمه Edge في التعامل مع FaultRules، بدءًا من كيفية الوصول إلى FaultRule واحدة لتنفيذها، وصولاً إلى كيفية التعامل مع شروط الخطوة "الداخلية" عند تشغيل FaultRule الخاصة بها. يقدّم هذا القسم أيضًا إرشادات حول الحالات التي يجب فيها تحديد FaultRules في <ProxyEndpoint> مقابل <TargetEndpoint>، ويصف العلاقة بين FaultRules وسياسة RaiseFault.

تنفيذ FaultRules

في ما يلي بإيجاز المنطق الذي يستخدمه Edge عندما ينتقل خادم وكيل لواجهة برمجة التطبيقات إلى حالة خطأ. يُرجى العِلم أنّ هناك اختلافًا طفيفًا بين تقييم FaultRules في ProxyEndpoint وTargetEndpoint.

1. يقيّم Edge قواعد FaultRules في ProxyEndpoint أو TargetEndpoint، وذلك حسب مكان حدوث الخطأ:
   • ProxyEndpoint: تبدأ الحافة بـ الأدنى <FaultRule> في ملف XML الخاص بالإعدادات وتنتقل إلى الأعلى، مع تقييم <Condition> لكل <FaultRule> (الشرط "الخارجي"، وليس شروط <Step> "الداخلية").
   • TargetEndpoint: يبدأ Edge بالعنصر الأعلى <FaultRule> في ملف XML الخاص بالإعداد، ثم ينتقل إلى الأسفل، ويقيّم <Condition> لكل <FaultRule> (الشرط "الخارجي"، وليس شروط <Step> "الداخلية").
2. تنفيذ first FaultRule الذي يكون شرطه صحيحًا إذا لم يتضمّن FaultRule أي شرط، تكون قيمته صحيحة تلقائيًا.
   • عند تنفيذ FaultRule، يتم تقييم جميع الخطوات داخل FaultRule بالترتيب، من الأعلى إلى الأسفل في إعداد XML. يتم تنفيذ الخطوات التي لا تتضمّن شروطًا تلقائيًا (يتم تنفيذ السياسات)، ويتم تنفيذ الخطوات التي تتضمّن <Condition> يتم تقييمها على أنّها "صحيحة" (لا يتم تنفيذ الشروط التي يتم تقييمها على أنّها "خاطئة").

   • في حال تنفيذ FaultRule، ولكن لم يتم تنفيذ أي خطوات في FaultRule (لأنّ شروطها تم تقييمها على أنّها "خطأ")، يتم عرض رسالة الخطأ التلقائية التي أنشأتها Edge لتطبيق العميل. <DefaultFaultRule> لا يتم تنفيذه، لأنّ Edge قد نفّذت بالفعل إحدى FaultRule.

3. في حال عدم تنفيذ أي FaultRule، ينفّذ Edge <DefaultFaultRule>، إذا كان متوفّرًا.

في ما يلي أمثلة تتضمّن تعليقات مضمّنة.

تنفيذ ProxyEndpoint

يتم تقييم ProxyEndpoint FaultRules من الأسفل إلى الأعلى، لذا ابدأ القراءة من آخر FaultRule في المثال التالي وانتقِل إلى الأعلى. اطّلِع على DefaultFaultRule في النهاية.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer"
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

تنفيذ TargetEndpoint

يتم تقييم TargetEndpoint FaultRules من الأعلى إلى الأسفل، لذا ابدأ القراءة من أول FaultRule في النموذج التالي وانتقِل إلى الأسفل. اطّلِع على DefaultFaultRule في النهاية.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE.
     A policy did not throw a FailedToResolveAPIKey error.
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer"
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

ترتيب قواعد الأعطال

كما ترى في المثال السابق، إنّ ترتيب وضع قواعد FaultRules مهم حسب ما إذا كان الخطأ يحدث في ProxyEndpoint أو TargetEndpoint.

على سبيل المثال:

السياسات التي يجب تضمينها

يمكنك تنفيذ أي سياسات من FaultRule عن طريق وضعها في "الخطوات". على سبيل المثال، يمكنك تنفيذ سياسة AssignMessage لتنسيق ردّ على تطبيق العميل، ثم تسجيل رسالة باستخدام سياسة MessageLogging. يتم تنفيذ السياسات بالترتيب الذي وضعتها به (من الأعلى إلى الأسفل في ملف XML).

لا يتم تشغيل قواعد الأعطال إلا في حالة حدوث خطأ (في ما يتعلق بالسمة continueOnError)

قد يبدو العنوان وكأنّنا نكرّر أنفسنا، ولكن هناك فارق بسيط يجب الانتباه إليه بشأن خطأ في الخادم الوكيل يؤدي إلى انتقال خادم وكيل لواجهة برمجة التطبيقات إلى حالة خطأ، أو بالأحرى، عدم انتقاله إلى حالة خطأ: السمة continueOnError في إحدى السياسات.

للتلخيص، يقيّم خادم وكيل لواجهة برمجة التطبيقات <FaultRules> و<DefaultFaultRule> فقط إذا دخل الخادم الوكيل في حالة خطأ. وهذا يعني أنّه حتى إذا تم تقييم شرط FaultRule على أنّه صحيح، لن يتم تشغيله إذا لم يكن الخادم الوكيل في حالة خطأ.

ومع ذلك، إليك مثال على حدوث خطأ وعدم انتقال الخادم الوكيل إلى حالة خطأ. في أي سياسة، يمكنك ضبط سمة على العنصر الرئيسي باسم continueOnError. تُعدّ هذه السمة مهمة جدًا في ما يتعلق بمعالجة الأخطاء، لأنّها تحدّد ما إذا كان الخادم الوكيل سيدخل في حالة خطأ في حال تعذّر تنفيذ السياسة. في معظم الحالات، عليك الاحتفاظ بالإعداد التلقائي continueOnError="false"، ما يؤدي إلى وضع الخادم الوكيل في حالة خطأ في حال تعذّر تنفيذ السياسة، وسيتم تفعيل معالجة الأخطاء المخصّصة. ومع ذلك، إذا continueOnError="true" (على سبيل المثال، إذا كنت لا تريد أن يؤدي تعذُّر تنفيذ Service Callout إلى إيقاف تنفيذ الخادم الوكيل)، لن ينتقل الخادم الوكيل إلى حالة خطأ في حال تعذُّر تنفيذ هذه السياسة، ولن يبحث الخادم الوكيل عن FaultRules.

للحصول على معلومات عن تسجيل الأخطاء عند continueOnError="true"، اطّلِع على معالجة أخطاء السياسات ضمن المسار الحالي.

مكان تحديد FaultRules: ProxyEndpoint أو TargetEndpoint

عندما يواجه خادم وكيل لواجهة برمجة التطبيقات خطأً، يحدث الخطأ إما في <ProxyEndpoint> (الطلب من تطبيق العميل أو الردّ عليه) أو في <TargetEndpoint> (الطلب من الخدمة المستهدَفة أو الردّ عليها). في أي مكان يحدث فيه هذا الخطأ، يبحث Edge عن FaultRules.

على سبيل المثال، إذا لم يكن الخادم المستهدف متاحًا (رمز حالة HTTP 503)، سيتم عرض حالة خطأ في الرد <TargetEndpoint>، ولن يستمر سير عمل الخادم الوكيل العادي لواجهة برمجة التطبيقات إلى <ProxyEndpoint>. إذا كانت لديك قواعد FaultRules محدّدة في <ProxyEndpoint> فقط، لن تتمكّن من معالجة هذا الخطأ.

إليك مثالاً آخر. إذا أدّت سياسة RaiseFault بشأن استجابة <ProxyEndpoint> إلى حدوث خطأ، لن يتم تنفيذ FaultRule في <TargetEndpoint>.

الفرق بين FaultRules وسياسة RaiseFault

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

وباختصار:

• يتم دائمًا تقييم قواعد الأعطال عندما يدخل خادم وكيل لواجهة برمجة التطبيقات في حالة خطأ.

• تتيح سياسة RaiseFault وضع خادم وكيل لواجهة برمجة التطبيقات في حالة خطأ عندما لا يحدث خطأ في الحالات العادية.

  على سبيل المثال، إذا أردت عرض خطأ في حال كان رمز حالة HTTP في الاستجابة من الخدمة المستهدَفة أكبر من 200، يمكنك إضافة سياسة RaiseFault إلى مسار الاستجابة. وسيبدو مشابهًا لهذا:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response>

  ترسل سياسة RaiseFault أيضًا رسالة خطأ إلى تطبيق العميل.

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

• بما أنّ FaultRule أو DefaultFaultRule يتم تنفيذهما بعد سياسة RaiseFault، ستكون الأولوية لبيانات استجابة FaultRule.
• يتم استخدام بيانات الردّ في سياسة RaiseFault (رمز الحالة أو عبارة السبب أو حمولة الرسالة) إذا لم يتم ضبط هذه البيانات بواسطة FaultRule أو DefaultFaultRule.
• إذا أضافت كلّ من سياسة RaiseFault وFaultRule عناوين HTTP مخصّصة، سيتم تضمينها في الاستجابة. تؤدي أسماء العناوين المكرّرة إلى إنشاء عنوان يتضمّن قيمًا متعددة.

في ما يلي مثال على ما يتم ضبطه من خلال سياسة RaiseFault وFaultRule، وما يتم إرجاعه إلى تطبيق العميل. تم تصميم الأمثلة لتكون موجزة، وليس لتطبيق أفضل الممارسات.

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: woops,gremlins

Status Code: [none]
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header:
  errorNote: woops

شروط البناء

الشروط هي المفتاح لتنفيذ FaultRule. يمكنك إنشاء شروط FaultRule بالطريقة نفسها التي تنشئ بها شروطًا أخرى في Edge، مثل الشروط الخاصة بالتدفقات الشرطية أو شروط RaiseFault.

لوضع بقية هذا القسم في سياقه، إليك نموذج لقاعدة خطأ تتضمّن شرط FaultRule خارجيًا وشرط Step داخليًا.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

المتغيرات الخاصة بأخطاء السياسة

تتوفّر المتغيّرات fault.name و{policy_namespace}.{policy_name}.failed عندما تعرض إحدى السياسات خطأً.

fault.name

عندما يتعذّر تنفيذ إحدى السياسات، يمكنك رصد الخطأ في شرط باستخدام المتغيّر fault.name. على سبيل المثال:

<Condition>(fault.name = "policy_error_name")</Condition>

يظهر اسم الخطأ في رسالة الخطأ التلقائية. على سبيل المثال، في ما يلي، اسم الخطأ هو FailedToResolveAPIKey. في هذه الحالة، يتم ضبط متغيّر سير باسم fault.name على القيمة FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

لذلك ستبدو الحالة على النحو التالي:

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

للاطّلاع على قائمة بأخطاء السياسات، يُرجى الرجوع إلى مرجع أخطاء السياسات.

{policy_namespace}.{policy_name}.failed

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

• سياسة RaiseFault: raisefault.failed (ينطبق ذلك على جميع سياسات RaiseFault)
• سياسة VerifyAPIKey: oauthV2.{policy_name}.failed، على سبيل المثال، oauthV2.Verify-API-Key-1.failed
• سياسة الحصة وسياسة SpikeArrest: ratelimit.{policy_name}.failed، على سبيل المثال، ratelimit.Quota-1.failed

المتغيّرات الأخرى المتاحة

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

• متغيّرات السياسة التي تعذّر تنفيذها
• متغيرات رسائل HTTP التي كانت متوفّرة عند حدوث الخطأ على سبيل المثال، إذا تم عرض خطأ في الاستجابة، يمكن أن تستخدم FaultRule في <TargetEndpoint> بيانات HTTP response.status.code وmessage.content وerror.content وما إلى ذلك. أو إذا تعذّر تنفيذ سياسة الحصة، يمكنك استخدام المتغيّر ratelimit.{quota_policy_name}.exceed.count. استخدِم أداة التتبُّع والمواضيع المرجعية للسياسات لمساعدتك في معرفة المتغيّرات وبيانات HTTP المتاحة.

مزيد من المعلومات

• الشروط: مرجع الشروط ومتغيّرات التدفق والشروط

• الأخطاء: مرجع خطأ السياسة
• المتغيرات: مرجع المتغيرات، واطّلِع على صفحات مرجع السياسات الفردية للمتغيرات المتاحة مع كل سياسة.

أفضل الممارسات للتعامل مع الأخطاء

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

في ما يلي بعض أفضل الممارسات في تصميم عملية معالجة الأخطاء وإنشائها:

• بالنسبة إلى كل FaultRule، قدِّم <Condition> "خارجي" (عنصر تابع للعنصر <Step>). يتم تلقائيًا تقييم قواعد الأعطال التي لا تتضمّن شرطًا خارجيًا على أنّها صحيحة. لا يتم استخدام شروط الخطوة "الداخلية" لتحديد ما إذا كانت FaultRule صحيحة أو خاطئة. لا يتم تقييم شروط الخطوة إلا بعد أن ينفّذ Edge عنصر FaultRule الذي يحتوي عليها. في FaultRule، من الشائع أن يكون هناك خطوات متعددة مع سياسات "تعيين الرسالة" (أو غيرها)، كل منها يتضمّن شرطًا للخطوة.

• للتعامل مع الأخطاء في سياسات متعددة من النوع نفسه (على سبيل المثال، سياسات متعددة بشأن الحصة)، أنشئ FaultRule واحدًا لكل خطأ في السياسة من المحتمل أن تتلقّاه. على سبيل المثال، أنشئ FaultRule لكل خطأ محتمل في سياسات الحصص، مثل QuotaViolation أو InvalidMessageWeight أو StartTimeNotSupported. (راجِع مرجع أخطاء السياسة للاطّلاع على أخطاء السياسة). عند اكتشاف أخطاء إضافية يجب التعامل معها، يمكنك الرجوع لاحقًا وإضافتها إلى FaultRules. لا بأس في تكرار هذه العملية، ولكنّها تتطلّب إعادة نشر الخادم الوكيل. يتيح لك هذا الأسلوب رصد النوع نفسه من الخطأ بغض النظر عن السياسة التي تعرضه، ما يجعل ملف XML الخاص بـ FaultRules فعّالاً.

  بعد ذلك، استخدِم شروط الخطوة الداخلية إذا كنت بحاجة إلى تحكّم أكثر دقة في الأخطاء. على سبيل المثال، إذا كنت تفرض حصة فردية للمطوّرين وحصة عالمية باستخدام سياستَين في مسار الطلب، اضبط شرط FaultRule "الخارجي" ليتم تشغيله عند حدوث الخطأ QuotaViolation (الذي يتم عرضه عندما تتجاوز الحصة في أي من الحالتين). بعد ذلك، اضبط شروط الخطوة لتقييم متغيرات exceed.count في كلتا سياستَي الحصة. يتم إرسال الخطأ ذي الصلة فقط إلى العميل (تجاوز حصة المطوّر أو تجاوز الحصة العامة). في ما يلي مثال على هذا الإعداد:

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>

  للاطّلاع على مثال آخر، راجِع سلسلة المحادثات هذه في "منتدى Apigee".

• للتعامل مع الأخطاء عند استخدام سياسة واحدة من نوع واحد، يمكنك استخدام قاعدة خطأ واحدة يتم تنفيذها عند تعذُّر تنفيذ هذه السياسة، وتضمين خطوات متعددة تتوافق مع كل خطأ محتمل. يساعد ذلك في الحفاظ على كفاءة ملف XML من خلال استخدام FaultRule واحد بدلاً من عدة FaultRule (واحد لكل نوع خطأ). على سبيل المثال:

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>

• أضِف FaultRules حيث ستحدث الأخطاء (من جهة العميل <ProxyEndpoint> أو من جهة الهدف <TargetEndpoint>). أدرِج FaultRules لكل سياسة تظهر في كل موقع.
• في FaultRules، يمكنك تنفيذ أي نوع من السياسات التي يمكنها عرض رسالة لتطبيق العميل، وتُعد سياسة AssignMessage مثالية لذلك. ننصحك أيضًا بتسجيل رسالة باستخدام سياسة MessageLogging إذا أردت تتبُّع الأخطاء.
• عند استخدام سياسات RaiseFault مع FaultRules، يجب تنسيق بيانات الاستجابة التي يتم إرسالها عند عرض كلّ من سياسة RaiseFault وFaultRule للبيانات. على سبيل المثال، إذا كانت سياسة RaiseFault تعيد ضبط رمز حالة HTTP، لا تضبط FaultRule رمز الحالة. أسوأ ما يمكن أن يحدث هو أن يتم عرض رمز الحالة التلقائي لتطبيق العميل.
• <DefaultFaultRule> التنفيذ:
  • إذا أردت أن يتم تنفيذ <DefaultFaultRule> دائمًا عندما لا يتم تنفيذ أي <Condition> أخرى، لا تضمِّن <Condition> فيها.
  • إذا كنت تريد تنفيذ <DefaultFaultRule> دائمًا حتى عند تنفيذ FaultRule أخرى، أضِف عنصر <AlwaysEnforce>true</AlwaysEnforce> الفرعي.

نمط معالجة الأخطاء المركزية والقابلة لإعادة الاستخدام

توضّح المشاركة التالية في &quot;منتدى Apigee&quot; نمطًا للتعامل المركزي مع الأخطاء بدون تكرار الرمز:

نمط معالجة الأخطاء لخوادم Apigee الوكيلة

إنشاء FaultRules

لإضافة FaultRule، عليك تعديل إعدادات XML الخاصة بـ ProxyEndpoint أو TargetEndpoint. يمكنك استخدام واجهة مستخدم Edge لإجراء هذا التعديل في جزء الرمز ضمن عرض تطوير لخادم وكيل لواجهة برمجة التطبيقات، أو تعديل ملف XML الذي يحدّد ProxyEndpoint أو TargetEndpoint.

إذا أنشأت FaultRules في واجهة مستخدم الإدارة، عليك أولاً إنشاء السياسات التي تريد تنفيذها، ثم إضافتها إلى إعدادات FaultRule. (سيظهر لك خطأ في واجهة المستخدم إذا حاولت حفظ FaultRule يشير إلى سياسة لم يتم إنشاؤها بعد).

إضافة سياسات إلى FaultRule

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

يوضّح المثال أدناه إعدادات نموذجية لسياسة AssignMessage:

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

يمكنك الآن استخدام هذه السياسة في FaultRule. لاحظ كيف تشير إلى سياسة AssignMessage بالاسم في FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

عند نشر الإعدادات أعلاه، سينفّذ خادم وكيل واجهة برمجة التطبيقات سياسة AssignMessage المسماة fault_invalidkey كلما قدّم تطبيق مفتاح واجهة برمجة تطبيقات غير صالح.

يمكنك تنفيذ سياسات متعددة في FaultRule، كما يوضّح المثال التالي:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

يتم تنفيذ السياسات بالترتيب المحدّد. على سبيل المثال، يمكنك استخدام سياسة MessageLogging أو سياسة ExtractVariables أو سياسة AssignMessage أو أي سياسة أخرى في FaultRule. يُرجى العِلم أنّ معالجة FaultRule تتوقّف فورًا في أيّ من الحالتين التاليتين:

• أي سياسة في FaultRule تؤدي إلى حدوث خطأ
• أي من السياسات في FaultRule هو من النوع RaiseFault

تحديد رسالة الخطأ المخصّصة التي يتم عرضها من خلال FaultRule

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

يستخدم مثال سياسة AssignMessage التالي العلامات <Payload> و<StatusCode> و<ReasonPhase> لتحديد استجابة الخطأ المخصّصة التي يتم إرسالها إلى العميل عند حدوث خطأ InvalidApiKey (راجِع مثال FaultRules السابق).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization.
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

يتضمّن هذا الردّ ما يلي:

• الحِزمة التي تحتوي على رسالة الخطأ وعنوان بريد إلكتروني للتواصل مع فريق الدعم
• رمز حالة HTTP الذي تم عرضه في الاستجابة.
• تمثّل هذه السمة عبارة السبب، وهي وصف موجز للخطأ.

إنشاء DefaultFaultRule

تعمل DefaultFaultRule كمعالج استثناء لأي خطأ لم تتم معالجته بشكل صريح من خلال FaultRule أخرى. إذا لم تتطابق شروط جميع قواعد FaultRules مع الخطأ، ستتعامل DefaultFaultRule مع الخطأ. فعِّل معالجة الأخطاء التلقائية من خلال إضافة العلامة <DefaultFaultRule> كعنصر فرعي من ProxyEndpoint أو TargetEndpoint.

على سبيل المثال، يحدّد إعداد TargetEndpoint أدناه DefaultFaultRule الذي يستدعي سياسة باسم ReturnGenericError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

يتم عادةً استخدام DefaultFaultRule لعرض رسالة خطأ عامة لأي خطأ غير متوقّع، مثل رسالة تتضمّن معلومات الاتصال بفريق الدعم الفني. يخدم هذا الردّ التلقائي الغرض المزدوج المتمثل في توفير معلومات مناسبة للمطوّرين مع إخفاء عناوين URL الخلفية أو غيرها من المعلومات التي قد تُستخدم لاختراق النظام.

على سبيل المثال، يمكنك تحديد سياسة AssignMessage التالية لعرض خطأ عام:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

أدرِج العنصر <AlwaysEnforce> في العلامة <DefaultFaultRule> لتنفيذ DefaultFaultRule لكل خطأ، حتى إذا تم تنفيذ FaultRule أخرى من قبل. تكون DefaultFaultRule دائمًا آخر FaultRule يتم تنفيذها:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

يتم استخدام DefaultFaultRule لتحديد نوع الخطأ الذي يحدث عندما يتعذّر عليك تحديده بطريقة أخرى. على سبيل المثال، يتعذّر على خادم وكيل واجهة برمجة التطبيقات تنفيذ عملية بسبب خطأ لا يمكنك تحديده. استخدِم DefaultFaultRule لاستدعاء سياسة AssignMessage التالية. تكتب هذه السياسة القيمة fault.name في عنوان باسم DefaultFaultHeader في الردّ:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

يمكنك بعد ذلك عرض العنوان في أداة تتبُّع Edge أو في الردّ لمعرفة سبب حدوث الخطأ.

إضافة تسجيل الرسائل إلى PostClientFlow

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

التعامل مع أخطاء السياسة ضمن المسار الحالي

تستخدِم الأمثلة المعروضة حتى الآن FaultRule في ProxyEndpoint أو TargetEndpoint للتعامل مع أي أخطاء في السياسة كجزء من حالة الخطأ. ويرجع ذلك إلى أنّ القيمة التلقائية للعنصر continueOnError في إحدى السياسات هي false، ما يعني أنّه عند حدوث خطأ في إحدى السياسات، يتم توجيه عنصر التحكّم إلى حالة الخطأ. وبعد حدوث الخطأ، لا يمكنك إعادة التحكم إلى مسار المعالجة العادي، وعادةً ما تعرض رسالة خطأ للتطبيق الذي طلب تنفيذ العملية.

ومع ذلك، إذا ضبطت العنصر continueOnError على true لسياسة ما، سيظل التحكّم في المسار الحالي وسيتم تنفيذ السياسة التالية في سلسلة المعالجة بعد السياسة التي تسبّبت في حدوث الخطأ. تتمثّل ميزة معالجة الخطأ في المسار الحالي في أنّه قد يكون لديك طريقة للتعافي من الخطأ لإكمال معالجة الطلب.

في ما يلي سياسة VerifyAPIKey باسم verify-api-key مع ضبط العنصر continueOnError على true:

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

إذا كان مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح، ستضبط سياسة VerifyAPIKey المتغيّر oauthV2.verify-api-key.failed على true، ولكن ستستمر المعالجة في المسار الحالي.

بعد ذلك، أضِف سياسة VerifyAPIKey كخطوة في PreFlow الخاص بـ ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
</ProxyEndpoint>

لاحظ كيف أنّ الخطوة التالية في PreFlow تستخدم شرطًا لاختبار وجود خطأ. في حال حدوث خطأ في سياسة VerifAPIKey، يتم تنفيذ السياسة المسماة FaultInFlow. وإلا، سيتم تخطّي سياسة FaultInFlow. يمكن أن تنفّذ سياسة FaultInFlow العديد من الإجراءات، مثل تسجيل الخطأ أو محاولة إصلاحه أو تنفيذ إجراء آخر.

إطلاق خطأ باستخدام سياسة RaiseFault

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

أحد استخدامات سياسة RaiseFault هو اختبار حالة معيّنة قد لا ترصدها سياسة أخرى. في المثال أعلاه، أضفت علامة <Condition> إلى علامة PreFlow <Step>، ما أدّى إلى تنفيذ السياسة FaultInFlow في حال استيفاء الشرط. إذا كانت FaultInFlow سياسة RaiseFault، سيتم نقل عنصر التحكّم إلى حالة الخطأ. أو يمكنك إدراج سياسة RaiseFault في أحد التدفقات لتصحيح الأخطاء واختبار FaultRules.

عندما تؤدي سياسة RaiseFault إلى ظهور خطأ، يمكنك استخدام FaultRule والشرط التاليَين لمعالجته:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

يُرجى العِلم أنّ اختبار الحالة يبحث عن خطأ باسم RaiseFault. تضبط سياسة RaiseFault دائمًا قيمة fault.name على RaiseFault.

التعامل المخصّص مع رموز خطأ HTTP من الخادم المستهدف

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

تتعامل Edge تلقائيًا مع رموز استجابة HTTP في النطاق 1xx-3xx على أنّها "ناجحة"، ومع رموز استجابة HTTP في النطاق 4xx-5xx على أنّها "فاشلة". وهذا يعني أنّ أي استجابة من خدمة الخلفية تتضمّن رمز استجابة HTTP يتراوح بين 4xx و5xx يؤدي تلقائيًا إلى استدعاء حالة الخطأ، والتي بدورها تعرض رسالة خطأ مباشرةً للعميل الذي أرسل الطلب.

يمكنك إنشاء معالِجات مخصّصة لأي رموز استجابة HTTP. على سبيل المثال، قد لا تريد التعامل مع جميع رموز استجابة HTTP في النطاق 4xx-5xx على أنّها "فشل"، بل فقط 5xx، أو قد تريد عرض رسائل خطأ مخصّصة لرموز استجابة HTTP 400 و500.

في المثال التالي، يمكنك استخدام السمة success.codes لضبط TargetEndpoint من أجل التعامل مع رموز استجابة HTTP 400 و500 على أنّها ناجحة، بالإضافة إلى رموز HTTP التلقائية. من خلال التعامل مع هذه الرموز على أنّها ناجحة، يتولّى TargetEndpoint معالجة رسالة الردّ بدلاً من استدعاء حالة الخطأ:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

كما ترى في هذا المثال، يمكنك استخدام أحرف البدل لضبط السمة success.codes على نطاق من القيم.

يؤدي ضبط السمة success.codes إلى استبدال القيم التلقائية. لذلك، إذا أردت إضافة رمز HTTP 400 إلى قائمة رموز النجاح التلقائية، اضبط هذه السمة على النحو التالي:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

ولكن إذا كنت تريد أن يتم التعامل مع رمز HTTP 400 فقط كرمز ناجح، اضبط السمة على النحو التالي:

<Property name="success.codes">400</Property>

يمكنك الآن تحديد معالِجات مخصّصة لرموز استجابة HTTP 400 و500 لعرض رسالة استجابة مخصّصة للتطبيق الذي يرسل الطلب. تستخدم TargetEndpoint التالية السياسة المسماة ReturnError للتعامل مع رموز استجابة HTTP 400 و500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

يؤدي إعداد TargetEndpoint هذا إلى أن تعالج السياسة المسماة ReturnError الاستجابة عندما تواجه TargetEndpoint رمز استجابة HTTP بقيمة 400 أو 500.

تصنيف الأخطاء

تنظّم "خدمات واجهة برمجة التطبيقات" الأخطاء في الفئات والفئات الفرعية التالية.

يصاحب الخطأ دائمًا وصف نصي لسبب حدوثه. عندما يبلغ النظام عن خطأ، يتم ملء مجموعة من السمات للمساعدة في تحديد المشاكل وحلّها. يتضمّن الخطأ المعلومات التالية:

• السبب
• السمات المخصّصة التي يحدّدها المستخدم