مشاركة عبر

التحقق من صحة العناوين

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

يتحقق النهج validate-headers من صحة عناوين الاستجابة مقابل مخطط واجهة برمجة التطبيقات.

هام

إذا قمت باستيراد واجهة برمجة التطبيقات باستخدام إصدار إدارة API قبل 2021-01-01-preview، قد لا يعمل النهج validate-headers. قد تحتاج إلى إعادة استيراد واجهة برمجة التطبيقات الخاصة بك باستخدام إصدار إدارة API 2021-01-01-preview أو إصدار أحدث.

إشعار

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

إشعار

تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. لمساعدتك في تكوين هذا النهج، يتيح المدخل محررًا موجهًا يستند إلى النموذج. تعلم كيفية إعداد نُهج APIM أو تعديلها.

نهج السياسة

<validate-headers specified-header-action="ignore | prevent | detect" unspecified-header-action="ignore | prevent | detect" errors-variable-name="variable name">
    <header name="header name" action="ignore | prevent | detect" />
</validate-headers>

سمات

السمة ‏‏الوصف مطلوبة افتراضي
إجراء رأس محدد الإجراء الذي سيتم تنفيذه لعناوين الاستجابة المحددة في مخطط واجهة برمجة التطبيقات. يتم السماح بتعبيرات النهج. ‏‏نعم‬ غير متوفر
إجراء رأس غير محدد الإجراء الذي سيتم تنفيذه لعناوين الاستجابة غير المحددة في مخطط واجهة برمجة التطبيقات. يتم السماح بتعبيرات النهج. ‏‏نعم‬ غير متوفر
errors-variable-name اسم المتغير في context.Variables لتسجيل أخطاء التحقق من الصحة فيه. تعبيرات النهج غير مسموح بها. لا غير متوفر

عناصر

الاسم ‏‏الوصف مطلوبة
العنوان أضف عنصرا واحدا أو أكثر للعناوين المسماة لتجاوز إجراءات التحقق من الصحة الافتراضية للعناوين في الاستجابات. لا

الإجراءات

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

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

  • يتجاوز الإجراء المحدد في العنصر التابع للنهج الإجراء المحدد للعنصر الأصل.

الإجراءات المتوفرة:

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

الاستخدام

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

ملاحظات الاستخدام

  • يمكن استخدام هذا النهج مرة واحدة فقط في قسم النهج.

السجلات

يتم تسجيل تفاصيل حول أخطاء التحقق من الصحة أثناء تنفيذ النهج إلى المتغير في context.Variables المحدد في السمة errors-variable-name في العنصر الجذر للنهج. عند تكوينه في إجراء prevent، يحظر خطأ التحقق من الصحة المعالجة الإضافية للطلب أو للاستجابة إضافية ويتم أيضاً نشره في الخاصية context.LastError.

للتحقيق في الأخطاء، استخدم نهج تتبع لتسجيل الأخطاء من متغيرات السياق إلى Application Insights.

الآثار المترتبة على الأداء

قد تؤثر إضافة نهج التحقق من الصحة على معدل نقل واجهة برمجة التطبيقات. تنطبق المبادئ العامة التالية:

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

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

مثال

<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />

أخطاء التحقق من الصحة

تنشئ إدارة واجهة برمجة التطبيقات أخطاء التحقق من صحة المحتوى بالتنسيق التالي:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

يسرد الجدول التالي جميع الأخطاء المحتملة من نُهج التحقق من الصحة.

  • التفاصيل: يمكن استخدامها للتحقيق في الأخطاء. ليست للمشاركة العلنية.
  • استجابة عامة: "خطأ" يُرجع إلى العميل. لا تسرب تفاصيل التنفيذ.

عندما يحدد نهج التحقق من الصحة الإجراء prevent وينتج خطأ، تتضمن الاستجابة من إدارة API تعليمة الحالة البرمجية HTTP: 400 عند تطبيق النهج في القسم الوارد، و502 عند تطبيق النهج في القسم الصادر.

الاسم النوع قاعدة التحقق من الصحة التفاصيل الاستجابة العامة الإجراء
التحقق من صحة المحتوى
RequestBody SizeLimit إن طول نص الطلب {size} ما يتجاوز الحد المكون وهو {maxSize} بايت. إن طول نص الطلب {size} ما يتجاوز الحد وهو {maxSize} بايت. كشف / منع
ResponseBody SizeLimit إن طول نص الطلب {size} ما يتجاوز الحد المكون وهو {maxSize} بايت. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{messageContentType} RequestBody غير محدد نوع المحتوى غير المحدد {messageContentType} غير مسموح به. نوع المحتوى غير المحدد {messageContentType} غير مسموح به. كشف / منع
{messageContentType} ResponseBody غير محدد نوع المحتوى غير المحدد {messageContentType} غير مسموح به. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
ApiSchema مخطط واجهة برمجة التطبيقات غير موجود أو تعذر حله. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
ApiSchema لا يحدد مخطط واجهة برمجة التطبيقات التعريفات. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{messageContentType} RequestBody / ResponseBody تعريف مفقود لا يحتوي مخطط واجهة برمجة التطبيقات على تعريف {definitionName} المرتبط بنوع المحتوى {messageContentType}. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{messageContentType} RequestBody رسالة غير صحيحة لا يحتوي نص الطلب على تعريف {definitionName}، المرتبط بنوع المحتوى {messageContentType}.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 لا يحتوي نص الطلب على تعريف {definitionName}، المرتبط بنوع المحتوى {messageContentType}.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 كشف / منع
{messageContentType} ResponseBody رسالة غير صحيحة لا يتوافق نص الاستجابة مع التعريف {definitionName} المرتبط بنوع المحتوى {messageContentType}.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
RequestBody ValidationException يتعذر التحقق من صحة نص الطلب لنوع المحتوى {messageContentType}.

{تفاصيل الاستثناء}		 تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
ResponseBody ValidationException يتعذر التحقق من صحة نص الاستجابة لنوع المحتوى {messageContentType}.

{تفاصيل الاستثناء}		 تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
التحقق من صحة المعلمات / التحقق من صحة الرؤوس
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader غير محدد {معلمة المسار / معلمة الاستعلام / العنوان} غير المحدد {paramName} غير مسموح به. {معلمة المسار / معلمة الاستعلام / العنوان} غير المحدد {paramName} غير مسموح به. كشف / منع
{headerName} عنوان الاستجابة غير محدد عنوان غير محدد {headerName} غير مسموح به. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
ApiSchema مخطط واجهة برمجة التطبيقات غير موجود أو تعذر حله. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
ApiSchema لا يحدد مخطط واجهة برمجة التطبيقات التعريفات. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader تعريف مفقود لا يحتوي مخطط واجهة برمجة التطبيقات على تعريف {definitionName} المرتبط بـ {معلمة الاستعلام / معلمة المسار / العنوان} {paramName}. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{paramName} QueryParameter / PathParameter / RequestHeader رسالة غير صحيحة لا يمكن أن يحتوي الطلب على قيم متعددة لـ{معلمة الاستعلام / معلمة المسار / العنوان} {paramName}. لا يمكن أن يحتوي الطلب على قيم متعددة لـ{معلمة الاستعلام / معلمة المسار / العنوان} {paramName}. كشف / منع
{headerName} عنوان الاستجابة رسالة غير صحيحة لا يمكن أن تحتوي الاستجابة على قيم متعددة للعنوان {headerName}. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{paramName} QueryParameter / PathParameter / RequestHeader رسالة غير صحيحة لا تتوافق قيمة {معلمة الاستعلام / معلمة المسار / العنوان} {paramName} مع التعريف.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 لا تتوافق قيمة {معلمة الاستعلام / معلمة المسار / العنوان} {paramName} مع التعريف.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 كشف / منع
{headerName} عنوان الاستجابة رسالة غير صحيحة لا تتوافق قيمة العنوان {headerName} مع التعريف.

{valError.Message} سطر: {valError.LineNumber}، موضع: {valError.LinePosition}		 تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{paramName} QueryParameter / PathParameter / RequestHeader رسالة غير صحيحة يتعذر توزيع قيمة {معلمة الاستعلام / معلمة المسار / العنوان} {paramName} وفقاً للتعريف.

{ex. الرسالة}		 تعذر توزيع قيمة {معلمة الاستعلام / معلمة المسار / العنوان} {paramName} وفقاً للتعريف.

{ex. الرسالة}		 كشف / منع
{headerName} عنوان الاستجابة رسالة غير صحيحة تعذر توزيع قيمة العنوان {headerName} وفقاً للتعريف. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
{paramName} QueryParameter / PathParameter / RequestHeader خطأ في التحقق من الصحة يتعذر التحقق من صحة {معلمة الاستعلام / معلمة المسار / العنوان} {paramName}.

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

{تفاصيل الاستثناء}		 تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع
التحقق من صحة التعليمات البرمجية للحالة
{status-code} رمز الحالة غير محدد التعليمة البرمجية للاستجابة {status-code} غير مسموح بها. تعذرت معالجة الطلب بسبب خطأ داخلي. تواصل مع مالك واجهة برمجة التطبيقات. كشف / منع

يسرد الجدول التالي جميع قيم "السبب" المحتملة لخطأ التحقق من الصحة مع قيم "الرسالة" المحتملة:

السبب رسالة
طلب غير صالح {Details} لمتغير السياق، {Public response} للعميل
الاستجابة غير مسموح بها {Details} لمتغير السياق، {Public response} للعميل

المحتوى ذو الصلة

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