التحقق من صحة تعليمة الحالة البرمجية
ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات
يتحقق النهج validate-status-code من صحة تعليمات الحالة البرمجية HTTP في الاستجابات مقابل مخطط واجهة برمجة التطبيقات. يمكن استخدام هذا النهج لمنع تسرب أخطاء الخلفية التي يمكن أن تحتوي على تتبع المكدس.
إشعار
الحد الأقصى لحجم مخطط واجهة برمجة التطبيقات الذي يمكن استخدامه بواسطة نهج التحقق من الصحة هذا هو 4 ميغابايت. إذا تجاوز المخطط هذا الحد، فستُرجع نُهج التحقق من الصحة الأخطاء في وقت التشغيل. لزيادة ذلك، يرجى التواصل مع الدعم.
إشعار
تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. لمساعدتك في تكوين هذا النهج، يتيح المدخل محررًا موجهًا يستند إلى النموذج. تعلم كيفية إعداد نُهج APIM أو تعديلها.
نهج السياسة
<validate-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
<status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>
سمات
| السمة | الوصف | مطلوبة | افتراضي |
|---|---|---|---|
| إجراء غير محدد للحالة-التعليمات البرمجية | الإجراء الذي سيتم تنفيذه لتعليمات الحالة البرمجية HTTP في الاستجابات غير المحددة في مخطط واجهة برمجة التطبيقات. يتم السماح بتعبيرات النهج. | نعم | غير متوفر |
| errors-variable-name | اسم المتغير في context.Variables لتسجيل أخطاء التحقق من الصحة فيه. تعبيرات النهج غير مسموح بها. |
لا | غير متاح |
عناصر
| Name | الوصف | مطلوب |
|---|---|---|
| تعليمة برمجية الحالة | أضف عنصرا واحدا أو أكثر برموز حالة HTTP لتجاوز إجراء التحقق الافتراضي برموز الحالة في الاستجابات. | لا |
سمات رمز الحالة
| السمة | الوصف | مطلوبة | افتراضي |
|---|---|---|---|
| الكود | تعليمة الحالة البرمجية HTTP لتجاوز إجراء التحقق من صحتها. | نعم | غير متوفر |
| إجراء | الإجراء الذي سيتم تنفيذه لتعليمات الحالة البرمجية المطابقة غير المحددة في مخطط واجهة برمجة التطبيقات. إذا تم تحديد تعليمة الحالة البرمجية في مخطط واجهة برمجة التطبيقات، لا يسري هذا التجاوز. | نعم | غير متوفر |
الإجراءات
تتضمن نهج التحقق من صحة المحتوى سمة واحدة أو أكثر تحدد إجراء، والتي تتخذها إدارة واجهة برمجة التطبيقات عند التحقق من صحة كيان في طلب واجهة برمجة التطبيقات أو استجابتها مقابل مخطط واجهة برمجة التطبيقات.
قد يتم تحديد إجراء للعناصر الممثلة في مخطط واجهة برمجة التطبيقات وأيضاً للعناصر غير الممثلة في مخطط واجهة برمجة التطبيقات، وذلك وفقاً للنهج.
يتجاوز الإجراء المحدد في العنصر التابع للنهج الإجراء المحدد للعنصر الأصل.
الإجراءات المتوفرة:
| الإجراء | الوصف |
|---|---|
| تجاهل | تخطي التحقق من الصحة. |
| منع | حظر معالجة الطلب أو الاستجابة، وتسجيل خطأ التحقق من الصحة المطول، وإرجاع خطأ. تتم مقاطعة المعالجة عند الكشف عن المجموعة الأولى من الأخطاء. |
| detect | تسجيل أخطاء التحقق من الصحة، دون مقاطعة معالجة الطلب أو الاستجابة. |
الاستخدام
- أقسام النهج: صادر، وعند حدوث الخطأ
- نطاقات النهج: العمومية، ومساحة العمل، والمنتج، وواجهة برمجة التطبيقات، والتشغيل
- البوابات: الكلاسيكية، الإصدار 2، الاستهلاك، المستضافة ذاتيا
ملاحظات الاستخدام
- يمكن استخدام هذا النهج مرة واحدة فقط في قسم النهج.
السجلات
يتم تسجيل تفاصيل حول أخطاء التحقق من الصحة أثناء تنفيذ النهج إلى المتغير في context.Variables المحدد في السمة errors-variable-name في العنصر الجذر للنهج. عند تكوينه في إجراء prevent، يحظر خطأ التحقق من الصحة المعالجة الإضافية للطلب أو للاستجابة إضافية ويتم أيضاً نشره في الخاصية context.LastError.
للتحقيق في الأخطاء، استخدم نهج تتبع لتسجيل الأخطاء من متغيرات السياق إلى Application Insights.
الآثار المترتبة على الأداء
قد تؤثر إضافة نهج التحقق من الصحة على معدل نقل واجهة برمجة التطبيقات. تنطبق المبادئ العامة التالية:
- كلما كان حجم مخطط واجهة برمجة التطبيقات أكبر، انخفض معدل النقل.
- كلما كانت الحمولة أكبر في طلب أو استجابة، انخفض معدل النقل.
- لحجم مخطط واجهة برمجة التطبيقات تأثير أكبر في الأداء من تأثير حجم الحمولة.
- قد يسبب التحقق من الصحة مقابل مخطط واجهة برمجة التطبيقات الذي هو أكبر في الحجم بعدة ميغابايت توقفاً مؤقتاً في الطلب أو الاستجابة في ظل شروط معينة. يكون التأثير أكثر وضوحاً في مستويات الاستهلاك والمطور من الخدمة.
نوصي بإجراء اختبارات التحميل مع أحمال عملك المتوقعة لتقييم تأثير نُهج التحقق من الصحة في معدل النقل في واجهة برمجة التطبيقات.
مثال
<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />
أخطاء التحقق من الصحة
تنشئ إدارة واجهة برمجة التطبيقات أخطاء التحقق من صحة المحتوى بالتنسيق التالي:
{
"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} للعميل |
النهج ذات الصلة
المحتوى ذو الصلة
لمزيد من المعلومات حول العمل مع النُهج، راجع: