خط‌مشی OASValidation

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

درباره خط‌مشی OASValidation

خط‌مشی OASValidation (اعتبارسنجی مشخصات OpenAPI) به شما امکان می‌دهد پیام درخواست یا پاسخ ورودی را دربرابر «مشخصات OpenAPI 3.0» (JSON یا YAML) اعتبارسنجی کنید. چه محتوایی اعتبار سنجی می‌شود؟ را ببینید.

خط‌مشی OASValidation نام «مشخصات OpenAPI» را برای استفاده در اعتبارسنجی هنگام اجرای مرحله‌ای که خط‌مشی به آن پیوست شده است مشخص می‌کند. «مشخصات OpenAPI» به‌عنوان منبعی در مکان استاندارد زیر در بسته پراکسی میانای برنامه‌سازی کاربردی ذخیره می‌شود: apiproxy/resources/oas. «مشخصات OpenAPI» باید پسوند .json، .yml، .yaml داشته باشد.

همان‌طور که در مدیریت منابع شرح داده شده است، بااستفاده از میانای کاربر یا API، یک «مشخصات OpenAPI» را به‌عنوان منبع به بسته پراکسی API اضافه کنید.

چه محتوایی معتبرسازی می‌شود؟

جدول زیر محتوای پیام درخواست را که توسط خط‌مشی OASValidation اعتبارسنجی شده است، براساس مؤلفه خلاصه می‌کند.

جدول زیر محتوای پیام پاسخ را که توسط خط‌مشی OASValidation اعتبارسنجی شده است، براساس مؤلفه خلاصه می‌کند.

نمونه‌ها

نمونه‌های زیر برخی‌از روش‌هایی را نشان می‌دهد که می‌توانید از خط‌مشی OASValidation برای اعتبارسنجی پیام‌ها دربرابر «مشخصات OpenAPI 3.0» استفاده کنید.

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

<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» را تعریف می‌کند.

<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>

<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>

این عنصر دارای ویژگی های زیر است که در همه سیاست ها مشترک است:

مرجع عنصر فرزند

این بخش عناصر فرزند <OASValidation> را شرح می‌دهد.

<DisplayName>

علاوه‌بر مشخصه name، از این مشخصه برای برچسب‌گذاری خط‌مشی در ویرایشگر پراکسی میانای کاربر مدیریت با نامی متفاوت و طبیعی‌تر استفاده کنید.

عنصر <DisplayName> برای همه خط‌مشی‌ها مشترک است.

عنصر <DisplayName> از نحو زیر استفاده می‌کند:

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

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

عنصر <DisplayName> هیچ مشخصه یا عنصر فرزندی ندارد.

<OASResource>

مشخصات OpenAPI را برای اعتبارسنجی مشخص می‌کند. می‌توانید این فایل را در این مکان‌ها ذخیره کنید:

• در محدوده پراکسی میانای برنامه‌سازی کاربردی در /apiproxy/resources/oas در دسته پراکسی میانای برنامه‌سازی کاربردی
• در بخش Resources نمای «ناوبر» ویرایشگر پراکسی میانای برنامه‌سازی کاربردی.

برای اطلاعات بیشتر، به مدیریت منابع مراجعه کنید.

می‌توانید «مشخصات OpenAPI» را بااستفاده از الگوی پیام، مثل {oas.resource.url}، مشخص کنید. در این حالت، مقدار متغیر جریان oas.resource.url (در آکولاد) ارزیابی می‌شود و در زمان اجرا در رشته بار مفید جایگزین می‌شود. برای اطلاعات بیشتر، به الگوهای پیام مراجعه کنید.

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

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

عنصر <OASResource> هیچ مشخصه یا عنصر فرزندی ندارد.

<گزینه‌ها>

گزینه‌های خط‌مشی را پیکربندی می‌کند.

<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، می‌توانید کنترل کنید که آیا اجرای جریان پس‌از خطای اعتبارسنجی ادامه یابد یا نه.

<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 Specification تعریف نشده‌اند پیکربندی می‌کند.

<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>

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

<Header> (فرزند <AllowUnspecifiedParameters>)

رفتار خط‌مشی را درصورت وجود پارامترهای سرصفحه در درخواست که در «مشخصات OpenAPI» تعریف نشده‌اند پیکربندی می‌کند.

برای اینکه پارامترهای سرصفحه در درخواست مشخص شوند که در «مشخصات OpenAPI» تعریف نشده‌اند، این پارامتر را روی true تنظیم کنید. درغیراین‌صورت، این پارامتر را روی false تنظیم کنید تا اجرای خط‌مشی ناموفق شود.

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

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

<Query> (فرزند <AllowUnspecifiedParameters>)

رفتار خط‌مشی را درصورت وجود پارامترهای پُرسمان در درخواست که در «مشخصات OpenAPI» تعریف نشده‌اند پیکربندی می‌کند.

برای اینکه پارامترهای پُرسمان در درخواست مشخص شوند که در «مشخصات OpenAPI» تعریف نشده‌اند، این پارامتر را روی true تنظیم کنید. درغیراین‌صورت، این پارامتر را روی false تنظیم کنید تا اجرای خط‌مشی ناموفق شود.

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

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

<Cookie> (فرزند <AllowUnspecifiedParameters>)

اگر پارامترهای کوکی در درخواست وجود داشته باشد که در «مشخصات OpenAPI» تعریف نشده باشد، رفتار خط‌مشی را پیکربندی می‌کند.

برای اینکه پارامترهای کوکی در درخواست مشخص شوند که در «مشخصات OpenAPI» تعریف نشده‌اند، این پارامتر را روی true تنظیم کنید. درغیراین‌صورت، این پارامتر را روی false تنظیم کنید تا اجرای خط‌مشی ناموفق شود.

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

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

<Source>

پیام JSON برای ارزیابی دربرابر حملات پایه‌بار JSON. این مقدار معمولاً روی request تنظیم می‌شود، زیرا معمولاً باید درخواست‌های ورودی از برنامه‌های کلاینت را ارزیابی کنید. برای ارزیابی پیام‌های پاسخ، روی پاسخ تنظیم کنید. روی پیام تنظیم کنید تا پیام درخواست را به‌طور خودکار ارزیابی کند وقتی خط‌مشی به جریان درخواست پیوست شده است و پیام پاسخ وقتی خط‌مشی به جریان پاسخ پیوست شده است.

<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 دردسترس هستند.

کدهای خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطایی را که Edge هنگام راه‌اندازی خطا در این خط‌مشی تنظیم می‌کند شرح می‌دهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه می‌دهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدو رسیدگی به اشکالات را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای خط‌مشی رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

متغیرهای خطا

این متغیرها زمانی تنظیم می‌شوند که این خط‌مشی در زمان اجرا باعث بروز خطا شود. برای اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانید را ببینید.

ویژگی‌های پشتیبانی‌شده مشخصات OpenAPI

خط‌مشی OASValidation از ویژگی‌های OpenAPI Specification که در جدول زیر به‌صورت خلاصه براساس دسته آمده است پشتیبانی می‌کند. ویژگی‌هایی که پشتیبانی نمی‌شوند نیز فهرست شده‌اند.

موضوعات مرتبط

• خط‌مشی محافظت دربرابر تهدید JSON
• خط‌مشی SOAPMessageValidation