مشاركة عبر

معالجة الأخطاء في نَهَج APIM

  • مقالة

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

من خلال توفير كائن ProxyError، تسمح Azure API Management للناشرين بالاستجابة لحالات الخطأ التي قد تحدث أثناء معالجة الطلبات. يتم الوصول إلى الكائن ProxyError من خلال الخاصية Context.LastError ويمكن استخدامه بواسطة النُهج في قسم النهجon-error. توفر هذه المقالة مرجعاً لقدرات معالجة الأخطاء في Azure API Management.

معالجة الأخطاء في API Management

تنقسم النُهج في Azure API Management إلى أقسام inbound وbackend وoutbound وon-error كما هو موضح في المثال التالي.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

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

إشعار

قسم on-error غير موجود في النُهج بشكل افتراضي. لإضافة قسم on-error إلى إحدى النُهج، استعرض للوصول إلى النهج المطلوب في محرر النهج وقم بإضافته. لمزيد من المعلومات حول نُهج التكوين، راجع Policies in API Management.

إذا لم يكن هناك قسم on-error، فسيتلقى المتصلون 400 أو 500 رسالة استجابة HTTP في حالة حدوث حالة خطأ.

النهج المسموح به عند الخطأ

يمكن استخدام النُهج التالية في قسم نهج on-error.

آخر خطأ

عند حدوث خطأ وانتقال عنصر التحكم إلى قسم نهج on-error، يتم تخزين الخطأ في خاصية Context.LastError، والتي يمكن الوصول إليها من خلال النُهج في قسم on-error. يتضمن آخر خطأ الخصائص التالية.

Name كتابة الوصف مطلوب
Source سلسلة يسمي العنصر الذي حدث فيه الخطأ. قد تكون إما نهج أو اسم خطوة مسار مضمن. ‏‏نعم‬
Reason سلسلة رمز خطأ سهل الاستخدام للآلة، والذي يمكن استخدامه في معالجة الأخطاء. لا
Message سلسلة وصف خطأ يمكن قراءته من قبل الإنسان. ‏‏نعم‬
Scope سلسلة اسم النطاق الذي حدث فيه الخطأ ويمكن أن يكون "عمومي" أو "منتج" أو "واجهة برمجة تطبيقات" أو "عملية" لا
Section سلسلة اسم القسم الذي حدث فيه الخطأ. القيم المحتملة: "الواردة"، "الخلفية"، "الصادرة"، أو "على خطأ". لا
Path سلسلة تحدد النهج المتداخل، على سبيل المثال "اختر[3]/عندما[2]". لا
PolicyId سلسلة قيمة السمة id، إذا حددها العميل، في النهج الذي حدث فيه الخطأ لا

تلميح

يمكنك الوصول إلى التعليمة البرمجية للحالة من خلال Context.Response.StatusCode.

إشعار

تحتوي جميع النُهج على سمة اختيارية id يمكن إضافتها إلى عنصر جذر النهج. إذا كانت هذه السمة موجودة في نهج عند حدوث حالة خطأ، فيمكن استرداد قيمة السمة باستخدام الخاصية context.LastError.PolicyId.

أخطاء محددة مسبقاً للخطوات المضمنة

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

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

أخطاء محددة مسبقاً للنُهج

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

المصدر الشرط السبب رسالة
rate-limit تم تجاوز حد المعدل تم تجاوز حد المعدل تم تجاوز حد المعدل
الحصة النسبية تم تجاوز الحصة النسبية QuotaExceeded نفاذ الحصة النسبية لمقدار المكالمات. سيتم تجديد الحصة النسبية في xx:xx:xx. -أو- نفاد الحصة النسبية للنطاق الترددي. سيتم تجديد الحصة النسبية في xx:xx:xx.
jsonp قيمة معلمة رد الاتصال غير صالحة (تحتوي على أحرف خاطئة) معلمة رد الاتصال غير صالحة قيمة معلمة رد الاتصال {callback-parameter-name} ليست معرّف JavaScript صالح.
عامل تصفية IP فشل تحليل عنوان IP الخاص بالمتصل من الطلب فشل في تحليل IP المتصل فشل في إنشاء عنوان IP للمتصل. تم رفض الوصول.
عامل تصفية IP عنوان IP المتصل ليس في القائمة المسموح بها Ip المتصل غير مسموح غير مسموح بعنوان IP للمتصل {ip-address}. تم رفض الوصول.
عامل تصفية IP عنوان IP المتصل في قائمة محظورة حظر IP المتصل تم حظر عنوان IP المتصل. تم رفض الوصول.
check-header لم يتم تقديم العنوان المطلوب أو القيمة مفقودة لم يتم العثور على العنوان لم يتم العثور على العنوان {header-name} في الطلب. تم رفض الوصول.
check-header لم يتم تقديم العنوان المطلوب أو القيمة مفقودة قيمة العنوان غير مسموح بها غير مسموح بقيمة {header-name} الخاصة بـ {header-value}. تم رفض الوصول.
تحقق من صحة jwt الرمز المميز لـ Jwt مفقود في الطلب TokenNotPresent JWT غير موجود.
تحقق من صحة jwt فشل التحقق من صحة التوقيع توقيع الرمز غير صالح <رسالة من مكتبة jwt>. تم رفض الوصول.
تحقق من صحة jwt جمهور غير صالح الجمهور المميز غير مسموح به <رسالة من مكتبة jwt>. تم رفض الوصول.
تحقق من صحة jwt مُصدر غير صالح مُصدر الرمز غير مسموح به <رسالة من مكتبة jwt>. تم رفض الوصول.
تحقق من صحة jwt انتهت صلاحية الرمز المميز انتهت صلاحية الرمز المميز <رسالة من مكتبة jwt>. تم رفض الوصول.
تحقق من صحة jwt لم يتم حل مفتاح التوقيع بواسطة معرف لم يتم العثور على مفتاح توقيع الرمز المميز <رسالة من مكتبة jwt>. تم رفض الوصول.
تحقق من صحة jwt المطالبات المطلوبة مفقودة من الرمز المميز لم يتم العثور على مطالبة الرمز يفتقد رمز JWT المميز المطالبات التالية: <c1>، <c2>، ..… تم رفض الوصول.
تحقق من صحة jwt قيم المطالبة غير متطابقة قيمة مطالبة الرمز غير مسموح بها غير مسموح بالمطالبة بقيمة {Claim-name} بقيمة {Claim-value}. تم رفض الوصول.
تحقق من صحة jwt حالات فشل التحقق الأخرى Jwt غير صالح <رسالة من مكتبة jwt>
طلب إعادة توجيه أو طلب إرسال لم يتم تلقي رمز حالة استجابة HTTP والعناوين من الخلفية ضمن المهلة المكونة المهلة متعدد

مثال

تعيين نهج API إلى:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

وسيؤدي إرسال طلب غير مصرح به إلى الاستجابة التالية:

استجابة خطأ غير مصرح بها

الخطوات التالية

للحصول على مزيدٍ من المعلومات التي تعمل مع النُهج، راجع: