سياسة OASالتحقق من الصحة

أنت تطّلع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
info

لمحة عن سياسة OASValidation

تتيح لك سياسة OASValidation (التحقّق من مواصفات OpenAPI) التحقّق من طلب وارد أو رسالة استجابة وفقًا لمواصفات OpenAPI 3.0 (JSON أو YAML). اطّلِع على المحتوى الذي يتم التحقّق منه.

تحدِّد سياسة OASValidation اسم مواصفة OpenAPI التي سيتم استخدامها للتحقّق من الصحة عند تنفيذ الخطوة التي تم إرفاق السياسة بها. يتم تخزين مواصفات OpenAPI كمورد في الموقع العادي التالي ضمن حِزمة وكيل واجهة برمجة التطبيقات: apiproxy/resources/oas. يجب أن تحتوي مواصفات OpenAPI على إضافة .json أو .yml أو .yaml.

أضِف مواصفات OpenAPI كمورد إلى حِزمة وكيل واجهة برمجة التطبيقات باستخدام واجهة المستخدم أو واجهة برمجة التطبيقات، كما هو موضّح في إدارة الموارد.

ما هو المحتوى الذي يتم التحقّق منه؟

يلخِّص الجدول التالي محتوى رسالة الطلب الذي يتم التحقّق منه من خلال سياسة OASValidation، حسب المكوّن.

المكونات طلب التحقق
المسار الأساسي للتحقّق من صحة المسار الأساسي الذي حدّده وكيل واجهة برمجة التطبيقات، يتم تجاهل المسار الأساسي المحدّد في مواصفات OpenAPI.
المسار للتحقّق من أنّ مسار الطلب (باستثناء المسار الأساسي) يتطابق مع أحد أنماط المسارات المحدّدة في مواصفات OpenAPI
فِعل للتحقّق من أنّه تمّ تعريف الفعل للمسار في مواصفات OpenAPI
نص طلب المحادثة
  • للتحقّق من توفّر نص الرسالة في الطلب، إذا لزم الأمر
  • يُحقِّق هذا الإجراء اختياريًا من صحة نص الرسالة وفقًا لنموذج نص طلب العملية في مواصفات OpenAPI. يمكنك ضبط هذا الخيار باستخدام <ValidateMessageBody>.

ملاحظة: لا تتحقّق السياسة من صحة نص رسالة الطلب وفقًا لمواصفات OpenAPI إلا إذا تم ضبط Content-Type على application/json. إذا لم يتم ضبط نوع المحتوى على application/json، سيتم اجتياز عملية التحقّق من صحة نص رسالة الطلب تلقائيًا (بدون التحقّق من صحة المحتوى).

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

يلخِّص الجدول التالي محتوى رسالة الاستجابة الذي يتم التحقّق منه من خلال سياسة OASValidation، حسب المكوّن.

المكونات التحقّق من صحة الردّ
المسار للتحقّق من أنّ مسار الطلب (باستثناء المسار الأساسي) يتطابق مع أحد أنماط المسارات المحدّدة في مواصفات OpenAPI
فِعل للتحقّق من أنّه تمّ تعريف الفعل للمسار في مواصفات OpenAPI
نص رسالة الاستجابة
  • للتحقّق من توفّر نص الرسالة في الاستجابة، إذا لزم الأمر
  • للتحقّق من توفّر رؤوس الاستجابة في مواصفات OpenAPI في رسالة الاستجابة، ومن تطابق قيمة رؤوس "الاستجابة" مع المخطّط
  • يمكنك اختياريًا التحقّق من صحة نص الرسالة وفقًا لنموذج نص الردّ في العملية في مواصفات OpenAPI. يمكنك ضبط هذا الخيار باستخدام <ValidateMessageBody>.

نماذج

توضّح الأمثلة التالية بعض الطرق التي يمكنك من خلالها استخدام سياسة OASValidation للتحقّق من صحة الرسائل وفقًا لمواصفات OpenAPI 3.0.

التحقّق من صحة رسالة الطلب

في المثال التالي، تتحقّق سياسة myoaspolicy من صحة نص رسالة الطلب مقارنةً بملف تعريف مخطّط نص رسالة طلب العملية المحدّد في مواصفات my-spec.json OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

إذا لم يكن نص الرسالة متوافقًا مع مواصفات OpenAPI، يتم عرض خطأ policies.oasvalidation.Failed.

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

يضبط المثال التالي السياسة على تعذُّر تنفيذها في حال تحديد مَعلمات رأس أو طلب بحث أو ملف تعريف ارتباط في الطلب غير محدّدة في مواصفات OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

عنصر <OASValidation>

تحدِّد سياسة التحقّق من مواصفات OpenAPI.

القيمة التلقائية راجِع علامة التبويب السياسة التلقائية أدناه.
هل هو مطلوب؟ مطلوب
النوع عنصر معقّد
العنصر الرئيسي timing fixed in amara
العناصر الفرعية <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

البنية

يستخدم العنصر <OASValidation> البنية التالية:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

السياسة التلقائية

يعرض المثال التالي الإعدادات التلقائية عند إضافة سياسة التحقّق من OAS إلى مسارك في واجهة مستخدم Apigee:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

مرجع العنصر الفرعي

يصف هذا القسم العناصر الفرعية لعنصر <OASValidation>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<OASResource>

تُستخدَم لتحديد مواصفات OpenAPI التي سيتم التحقّق منها. يمكنك تخزين هذا الملف:

  • في نطاق وكيل واجهة برمجة التطبيقات ضمن /apiproxy/resources/oas في حِزمة وكيل واجهة برمجة التطبيقات
  • في قسم Resources من عرض "المستكشف" في "محرر الوكيل لواجهة برمجة التطبيقات".

لمزيد من المعلومات، يُرجى الاطّلاع على إدارة الموارد.

يمكنك تحديد مواصفات OpenAPI باستخدام نموذج رسالة، مثل {oas.resource.url}. في هذه الحالة، سيتم تقييم قيمة متغيّر مسار الإحالة الناجحة oas.resource.url (في الأقواس المتعرجة) واستبدالها في سلسلة الحمولة أثناء التشغيل. لمزيد من المعلومات، يُرجى الاطّلاع على نماذج الرسائل.

القيمة التلقائية بدون
هل هو مطلوب؟ مطلوب
النوع سلسلة
العنصر الرئيسي <OASValidation>
العناصر الفرعية بدون

البنية

يستخدم العنصر <OASResource> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

مثال

يشير المثال التالي إلى مواصفة my-spec.yaml المخزّنة ضمن /apiproxy/resources/oas في حزمة الوكيل لواجهة برمجة التطبيقات:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

لا يحتوي عنصر <OASResource> على أي سمات أو عناصر ثانوية.

<Options>

ضبط خيارات السياسة

القيمة التلقائية timing fixed in amara
هل هو مطلوب؟ اختياري
النوع النوع المعقّد
العنصر الرئيسي <OASValidation>
العناصر الفرعية <ValidateMessageBody>
<AllowUnspecifiedParameters>

البنية

يستخدم العنصر <Options> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

مثال

يضبط المثال التالي خيارات السياسة. وسيتم وصف كل خيار بالتفصيل أدناه.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

يحدِّد ما إذا كان على السياسة التحقّق من صحة نص الرسالة مقارنةً بمخطّط نص طلب العملية في مواصفات OpenAPI. اضبط القيمة على true للتحقّق من صحة محتويات نص الرسالة. اضبطه على false للتحقّق من توفّر نص الرسالة فقط.

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

القيمة التلقائية خطأ
هل هو مطلوب؟ اختياري
النوع منطقي
العنصر الرئيسي <Options>
العناصر الفرعية بدون

البنية

يستخدم العنصر <ValidateMessageBody> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

مثال

يتيح المثال التالي التحقّق من محتوى نص الرسالة:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

لضبط سلوك السياسة في حال توفّر مَعلمات رأس أو طلب بحث أو ملفّ تعريف ارتباط في الطلب لم يتمّ تحديدها في مواصفات OpenAPI

القيمة التلقائية timing fixed in amara
هل هو مطلوب؟ اختياري
النوع النوع المعقّد
العنصر الرئيسي <Options>
العناصر الفرعية <Header>
<Query>
<Cookie>

البنية

يستخدم العنصر <AllowUnspecifiedParameters> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

مثال

يضبط المثال التالي السياسة على تعذُّر تنفيذها في حال تحديد مَعلمات رأس أو طلب بحث أو ملف تعريف ارتباط في الطلب غير محدّدة في مواصفات OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

تضبط هذه السياسة سلوك السياسة في حال توفّر مَعلمات عنوان في الطلب لم يتم تحديدها في مواصفات OpenAPI.

للسماح بتحديد مَعلمات الرأس في الطلب التي لم يتم تحديدها في مواصفات OpenAPI، اضبط هذه المَعلمة على true. بخلاف ذلك، اضبط هذه المَعلمة على false لتسبب تعذُّر تنفيذ السياسة.

القيمة التلقائية صحيح
هل هو مطلوب؟ منطقي
النوع النوع المعقّد
العنصر الرئيسي <AllowUnspecifiedParameters>
العناصر الفرعية بدون

البنية

يستخدم العنصر <Header> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

مثال

يضبط المثال التالي السياسة على أنّها غير ناجحة إذا تم تحديد مَعلمة عنوان في الطلب لم يتم تحديدها في مواصفات OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (طفل <AllowUnspecifiedParameters>)

لضبط سلوك السياسة في حال توفّر مَعلمات طلبات بحث في الطلب لم يتم تحديدها في مواصفات OpenAPI

للسماح بتحديد مَعلمات طلبات البحث في الطلب التي لم يتم تحديدها في مواصفات OpenAPI، اضبط هذه المَعلمة على true. بخلاف ذلك، اضبط هذه المَعلمة على false لتسبب تعذُّر تنفيذ السياسة.

القيمة التلقائية صحيح
هل هو مطلوب؟ منطقي
النوع النوع المعقّد
العنصر الرئيسي <AllowUnspecifiedParameters>
العناصر الفرعية بدون

البنية

يستخدم العنصر <Query> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

مثال

يضبط المثال التالي السياسة على أنّها غير ناجحة في حال تحديد مَعلمة طلب بحث في الطلب لم يتم تحديدها في مواصفات OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

لضبط سلوك السياسة في حال توفّر مَعلمات ملفات تعريف الارتباط في الطلب غير المحدّدة في مواصفات OpenAPI

للسماح بتحديد مَعلمات ملفات تعريف الارتباط في الطلب التي لم يتم تحديدها في مواصفات OpenAPI، اضبط هذه المَعلمة على true. بخلاف ذلك، اضبط هذه المَعلمة على false لتسبب تعذُّر تنفيذ السياسة.

القيمة التلقائية صحيح
هل هو مطلوب؟ منطقي
النوع النوع المعقّد
العنصر الرئيسي <AllowUnspecifiedParameters>
العناصر الفرعية بدون

البنية

يستخدم العنصر <Cookie> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

مثال

يضبط المثال التالي السياسة على أنّها غير ناجحة في حال تحديد مَعلمة طلب بحث في الطلب لم يتم تحديدها في مواصفات OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

رسالة JSON التي سيتم تقييمها ضد هجمات حِزم JSON يتم ضبط هذا الإعداد عادةً على request، لأنّك ستحتاج عادةً إلى تقييم الطلبات الواردة من تطبيقات العميل. اضبط القيمة على response لتقييم رسائل الردّ. اضبط القيمة على message لتقييم رسالة الطلب تلقائيًا عند إرفاق السياسة بمسار الطلب ورسالة الردّ عند إرفاق السياسة بمسار الردّ.

القيمة التلقائية طلب
هل هو مطلوب؟ اختياري
النوع سلسلة
العنصر الرئيسي <Source>
العناصر الفرعية بدون

البنية

يستخدم العنصر <Source> البنية التالية:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

مثال

يُقيّم المثال التالي تلقائيًا رسالة الطلب عند إرفاق السياسة بمسار الطلب ورسالة الردّ عند إرفاق السياسة بمسار الردّ:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

لا يحتوي عنصر <Source> على سمات أو عناصر ثانوية.

المخططات

يتم تحديد كل نوع سياسة من خلال مخطّط XML (.xsd). يُرجى العِلم أنّ مخطّطات السياسات متاحة على GitHub.

رموز الخطأ

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.oasvalidation.Failed 500 Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable 500

Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.

steps.oasvalidation.NotMessageVariable 500

<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
ResourceDoesNotExist OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oasvalidation.myoaspolicy.failed = true

ميزات مواصفات OpenAPI المتوافقة

تتيح سياسة OASValidation ميزات OpenAPI Specification التي تم تلخيصها في الجدول التالي حسب الفئة. ويتم أيضًا إدراج الميزات غير المتاحة.

الفئة معلومات معتمَدة غير متاح
تنسيقات أنواع البيانات boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
ثنائي
بايت
كلمة المرور
عنصر المُميِّز mapping
propertyName
لا ينطبق
عنصر نوع الوسائط مخطّط ترميز
مثال
أمثلة
عنصر العمليات parameters
requestBody
responses
security (partial support)
عمليات تسجيل المكالمات
القديمة
الخوادم
عنصر "المَعلمات" allowEmptyValue
in (query, header, path)
required
responses
schema
style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

ملاحظة: يتيح deepObject استخدام المَعلمات من النوع سلسلة فقط، ولا يتيح استخدام الصفائف والكائنات المُدمجة.
allowReserved
deprecated
example
examples
content
عنصر المسارات delete
get
head
options
parameters
patch
post
put
trace
variables
الخوادم
عنصر نص الطلب application/json
application/hal+json
application/x-www-form-urlencoded (encoding object not supported)
content
required
application/xml
multipart/form-data
text/plain
text/xml
عنصر الاستجابة application/json
application/hal+json
application/x-www-form-urlencoded (encoding object not supported)
content
headers
application/xml
links
text/plain
text/xml
عنصر Responses التلقائية
رمز حالة HTTP
لا ينطبق
عنصر المخطط $ref
additionalProperties (صيغة العلامة المنطقية فقط)
allOf (يتم تجاهلها إذا كان additionalProperties هو false)
anyOf
enum
exclusiveMaximum/exclusiveMinimum
format
items
maximum/minimum
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
properties
required
title
type
uniqueItems
deprecated
example
readOnly
writeOnly
xml
عنصر مخطّط الأمان في (header، query) (يتم تجاهلها إذا كان type هو http)
اسم
نوع (apiKey، http)
bearerFormat
flows
openIdConnectUrl
scheme
عنصر الخادم متغيّرات
عنوان URL
تعريفات الخوادم المتعددة

مواضيع ذات صلة