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

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

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

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

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

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

الفيديوهات

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

كيفية حدوث الأخطاء

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

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

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

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

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

أخطاء مخصّصة

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

يمكنك إضافة سياسة FetchFault إلى مسار الخادم الوكيل لواجهة برمجة التطبيقات تمامًا كما تفعل مع أي سياسة أخرى. ضِمن في المثال التالي على إعدادات الخادم الوكيل، تم إرفاق سياسة Raise-Fault-1 رد TargetEndpoint. إذا كانت كلمة "غير متاح" موجود في الاستجابة من الهدف يتم تنفيذ سياسة AskFault، وتعرض رسالة خطأ.

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

والهدف من ذلك هو توضيح إمكانية حدوث أخطاء مخصَّصة. ندخل في مزيد من التفاصيل حول سياسة AskFault في مقارنة قواعد الخطأ بسياسة النصيFault .

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

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

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

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

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

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

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

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

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

التحقق من قواعد الخطأ

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

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) قاعدة خطأ تؤدي إلى تنفيذ السياسة عندما ينتقل الوكيل إلى حالة خطأ.

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> من ضبط الخادم الوكيل، ستضيف كتلة XML <FaultRules> تحتوي على أو أكثر من أقسام <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 الشرط لتنفيذ السياسة فقط إذا كان الشرط true. إذا كانت هناك العديد من قواعد الخطأ التي لتقييمه على true، ستنفذ Edge أول عملية صحيحة. (ملاحظة مهمة: يختلف ترتيب تقييم قواعد الأخطاء من أعلى إلى أسفل أو من أسفل إلى أعلى بين TargetEndpoint وProxyEndpoint، كما هو موضح في قسم عمليات قسم FaultRules ومنطق التنفيذ). إذا لم تقم بتضمين شرط، فستبدأ قاعدة الخطأ (FultRule) يكون true تلقائيًا. لكن هذه ليست أفضل ممارسة. يجب أن يكون لكل خطأ قاعدة خاصية الشرط.

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

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

قواعد أخطاء متعددة ومنطق التنفيذ

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

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

تنفيذ FaultRules

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

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

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

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 من أعلى إلى أسفل، لذا ننصحك ببدء القراءة من 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>

ترتيب قاعدة الخطأ

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

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

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

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

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

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

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

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

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

أين لتحديد FaultRules: ProxyEndpoint أو TargetEndpoint

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

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

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

مقارنة بين سياسة FaultRules وسياسة RestoreFault

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

وباختصار:

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

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

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

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

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

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

• بما أنه يتم تنفيذ خطأ FaultRule أو defaultFaultRule بعد سياسة التسليم FaultRule، فإن يتم الفوز ببيانات استجابة FaultRule.
• أما بيانات الاستجابة لسياسة riseFault (رمز الحالة أو عبارة السبب أو حمولة الرسائل) فهي إذا لم يتم ضبط هذه البيانات بواسطة FaultRule أو defaultFaultRule.
• إذا أضافت كل من سياسة \tFault وFultRule عناوين HTTP مخصصة، يتم تضمين كلتيهما في الرد. تؤدي أسماء العناوين المكررة إلى إنشاء عنوان يحتوي على قيم متعددة.

في ما يلي مثال لما تم ضبطه من خلال سياسة riseFault وقاعدة الخطأ (FultRule) وما يتم وإعادته إلى تطبيق العميل. تم تصميم العينات للإيجاز، وليس لأفضل الممارسات.

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، مثل التدفقات الشرطية أو شروط AskFault.

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

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

• سياسة SpamFault: raisefault.failed (ينطبق ذلك على جميع سياسات riseFault)
• سياسة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>). يتم تلقائيًا تقييم قواعد الأخطاء التي لا تتضمن شرطًا خارجيًا إلى true. "داخلي" لا يتم استخدام شروط الخطوة لتحديد ما إذا كانت قاعدة الخطأ صحيحة. أو false. لا يتم تقييم شروط الخطوة إلا بعد تنفيذ Edge لقاعدة الخطأ التي تحتوي عليها. في قاعدة الخطأ، من المعتاد أن يكون لديك خطوات متعددة مع سياسات "تعيين رسالة" (أو غيرها)، ولكل منها شرط الخطوة.

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

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

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

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

تصف المشاركة التالية في منتدى Apigee نمطًا للمعالجة المركزية للأخطاء بدون تكرار التعليمات البرمجية:

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

إنشاء قواعد الخطأ

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

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

يتم تنفيذ السياسات بالترتيب المحدّد. على سبيل المثال، يمكنك استخدام دالة الرسم سياسة تسجيل الرسائل وسياسة استخراج المتغيّرات سياسة assignMessage أو أي سياسة أخرى في FaultRule (قاعدة الخطأ). تجدر الإشارة إلى أنّ معالجة خطأ FaultRule تتوقف على الفور في حال حدوث أي من هاتين الحالتين. الحدوث:

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

يساعد تعريف رسالة خطأ مخصصة ناتجة عن خطأ FaultRule

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

يستخدم مثال سياسة AssignMessage التالي السمة <Payload>. العلامتين <StatusCode> و<ReasonPhase> لتحديد الحجم المخصص تم إرسال ردّ إلى العميل بشأن خطأ غير صالحApiKey (يُرجى الاطّلاع على قواعد 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 الخطأ. تمكين معالجة الأخطاء الافتراضية عن طريق إضافة علامة <DefaultFaultRule> كعنصر ثانوي في ProxyEndpoint أو نقطة النهاية المستهدفة.

على سبيل المثال، تحدد ضبط TargetEndpoint أدناه قاعدة defaultFaultRule التي تستدعي سياسة باسم ReturnعامةError:

<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 على كل خطأ، حتى في حال تنفيذ قاعدة خطأ أخرى بالفعل. قاعدة defaultFaultRule هي قاعدة الخطأ الأخيرة دائمًا لتنفيذه:

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

التعامل مع أخطاء السياسات ضمن التدفق الحالي

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

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

يظهر أدناه سياسة تحققAPIKey باسم 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>

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

عرض خطأ باستخدام FetchFault السياسة

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

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

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

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

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

معالجة مخصصة لرموز خطأ HTTP من الخادم الهدف

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

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

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

في المثال التالي، يمكنك استخدام السمة success.codes لضبط التعامل مع رمز استجابة HTTP 400 و500 باعتبارهما بنجاح، إلى جانب HTTP الافتراضي لـ TargetEndpoint الرموز. من خلال التعامل مع هذه الرموز على أنها ناجحة، تتولى 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 وHTTP 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.

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

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

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

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