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

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

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

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

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

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

الفيديوهات الطويلة

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

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

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

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

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

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

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

أخطاء مخصّصة

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

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

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

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

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

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

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

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

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

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

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

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

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

التحقّق من وجود Faultالقواعد

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

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> من إعدادات الخادم الوكيل، ستضيف كتلة XML <FaultRules> تحتوي على قسم <FaultRule> فردي واحد أو أكثر. وتمثّل كل قاعدة خطأ خطأً مختلفًا تريد التعامل معه. في هذا المثال البسيط، سنستخدم Faultقاعدة واحدة فقط لتوضيح كونها مؤلفة منها.

عليك أيضًا إضافة <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>

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

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

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

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

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

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

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

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

تنفيذ Faultالقواعد

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

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

   • في حال تنفيذ FaultRule ولكن لم يتم تنفيذ أي خطوات في FaultRule (لأنه يتم تقييم شروطها إلى "false")، يتم إرجاع رسالة الخطأ التلقائية التي أنشأها 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>

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

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

مثال:

السياسات المطلوب تضمينها

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

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

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

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

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

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

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

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

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

إليك مثالاً آخر. إذا أدّت سياسة GrowFault في الاستجابة <ProxyEndpoint> إلى ظهور خطأ، لن يتم تنفيذ Faultقاعدة في <TargetEndpoint>.

مقارنة بين Faultالقواعد وسياسة riseFault

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

وباختصار:

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

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

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

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

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

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

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

في ما يلي مثال على ما تم ضبطه في كل من سياسة ReceivedFault و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، مثل التدفقات الشرطية أو شروط PrepareFault.

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

• سياسة riseFault: raisefault.failed (السياسة نفسها لجميع سياسات AcceleratedFault)
• سياسة CheckAPIKey: oauthV2.{policy_name}.failed، على سبيل المثال، oauthV2.Verify-API-Key-1.failed
• سياسة الحصة وسياسة SpikeArrest: ratelimit.{policy_name}.failed، على سبيل المثال، ratelimit.Quota-1.failed

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

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

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

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

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

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

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

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

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

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

• لمعالجة الأخطاء في سياسات متعددة من النوع نفسه (على سبيل المثال، سياسات الحصص المتعددة)، أنشِئ قاعدة خطأ واحدة لكل خطأ سياسة يُحتمل أن يظهر لك. مثلاً، يمكنك إنشاء Faultقاعدة لكل خطأ محتمل في سياسات الحصص، مثل QuotaViolation وInvalidMessageWeight وStartTimeNotSupported. (يمكنك الاطّلاع على مرجع الأخطاء في السياسة لمعرفة الأخطاء المتعلقة بالسياسة. وبينما تكتشف أخطاء إضافية يجب معالجتها، يمكنك الرجوع لاحقًا وإضافتها إلى Faultالقواعد. لا بأس في أن تكون متكررة، على الرغم من أنها تتطلب إعادة النشر بالوكيل). وتتيح لك هذه الطريقة رصد نوع الخطأ نفسه بغضّ النظر عن السياسة التي تعرضها، ما يجعل ملف 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 باستخدام قاعدة FaultRequest واحدة بدلاً من عدة قواعد FaultRequests (واحدة لكل نوع خطأ). مثال:

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

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

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

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

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

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

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

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

إضافة سياسات إلى قاعدة خطأ

يمكنك وضع أي سياسة في FaultYes، إلا أنّك تستخدم عادةً سياسة 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 أو سياسة استخراج المتغيرات أو سياسة التعيين أو أي سياسة أخرى في FaultRule. تجدُر الإشارة إلى أنّ معالجة Faultقاعدة تتوقف فورًا في حال حدوث أي من الحالتَين التاليتَين:

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

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

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

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

<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 الذي يتم عرضه في الاستجابة.
• عبارة السبب، وهي وصف موجز للخطأ.

إنشاء قاعدة خطأ تلقائية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يظهر أدناه سياسة CheckAPIKey المسماة 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>

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

بعد ذلك، يمكنك إضافة سياسة CheckAPIKey كخطوة في ميزة 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>  

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

إرسال خطأ باستخدام سياسة ikeFault

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

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

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

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

تجدر الإشارة إلى أنّ الحالة تختبر خطأ يُسمى RaiseFault. تضبط سياسة ikeFault قيمة 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 من أجل عرض رسالة استجابة مخصّصة للتطبيق المعنيّ. وتستخدم نقطة النهاية التالية السياسة المسماة 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.

تصنيف الخطأ

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

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

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