مشاركة عبر

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

  • مقالة

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

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

هام

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

إشعار

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

إشعار

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

نهج السياسة

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

سمات

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

عندما يتم توفير القيمة في عنصر headers، أو query، أو path، فإن القيمة تتجاوز قيمة specified-parameter-action في العنصر validate-parameters. يتم السماح بتعبيرات النهج.		 ‏‏نعم‬ غير متوفر
إجراء معلمة غير محدد إجراء ينبغي تنفيذه لمعلمات الطلب غير المحددة في مخطط واجهة برمجة التطبيقات.

عندما يتم توفير القيمة في عنصر headers، أو query، فإن القيمة تتجاوز قيمة unspecified-parameter-action في العنصر validate-parameters. يتم السماح بتعبيرات النهج.		 ‏‏نعم‬ غير متوفر
errors-variable-name اسم المتغير في context.Variables لتسجيل أخطاء التحقق من الصحة فيه. تعبيرات النهج غير مسموح بها. لا ‏‫غير متاح

عناصر

Name ‏‏الوصف مطلوب
رؤوس أضف هذا العنصر وعنصرا فرعيا واحدا أو أكثر parameter لتجاوز إجراءات التحقق الافتراضية لبعض المعلمات المسماة في الطلبات. إذا كانت المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين specified-parameter-action ذي المستوى الأعلى. إذا لم تكن المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين unspecified-parameter-action ذي المستوى الأعلى. لا
استعلام أضف هذا العنصر وعنصرا فرعيا واحدا أو أكثر parameter لتجاوز إجراءات التحقق الافتراضية لبعض معلمات الاستعلام المسماة في الطلبات. إذا كانت المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين specified-parameter-action ذي المستوى الأعلى. إذا لم تكن المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين unspecified-parameter-action ذي المستوى الأعلى. لا
path أضف هذا العنصر وعنصرا فرعيا واحدا أو أكثر parameter لتجاوز إجراءات التحقق الافتراضية لمعلمات مسار URL معينة في الطلبات. إذا كانت المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين specified-parameter-action ذي المستوى الأعلى. إذا لم تكن المعلمة محددة في مخطط واجهة برمجة التطبيقات، تتجاوز هذه القيمة تكوين unspecified-parameter-action ذي المستوى الأعلى. لا

الإجراءات

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

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

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

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

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

الاستخدام

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

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

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

السجلات

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

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

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

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

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

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

مثال

في هذا المثال، يتم التحقق من صحة جميع معلمات الاستعلام والمسار في وضع الوقاية والعناوين في وضع الكشف. تم تجاوز التحقق من الصحة لعدة معلمات عنوان:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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