Kebijakan OASValidation

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Tentang kebijakan OASValidation

Kebijakan OASValidation (Validasi Spesifikasi OpenAPI) memungkinkan Anda memvalidasi permintaan atau pesan respons yang masuk terhadap Spesifikasi 3.0 OpenAPI, menggunakan format JSON atau YAML. Lihat Konten apa yang divalidasi?

Kebijakan OASValidation menentukan nama Spesifikasi OpenAPI yang akan digunakan untuk validasi saat langkah yang terkait dengan kebijakan dijalankan. Spesifikasi OpenAPI disimpan sebagai resource di lokasi standar berikut dalam paket proxy API: apiproxy/resources/oas. Dokumen Spesifikasi OpenAPI harus memiliki ekstensi .json, .yml, atau .yaml.

Tambahkan Spesifikasi OpenAPI sebagai resource ke paket proxy API menggunakan UI atau API, seperti yang dijelaskan dalam Mengelola resource.

Kebijakan ini adalah kebijakan Standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Konten apa yang divalidasi?

Tabel berikut merangkum konten pesan permintaan yang divalidasi oleh kebijakan OASValidation, menurut komponen.

Tabel berikut merangkum konten pesan respons yang divalidasi oleh kebijakan OASValidation, menurut komponen.

Sampel

Contoh berikut menunjukkan beberapa cara Anda dapat menggunakan kebijakan OASValidation untuk memvalidasi pesan terhadap Spesifikasi 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>

Elemen <OASValidation>

Menentukan kebijakan Validasi Spesifikasi 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>

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <OASValidation>.

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Elemen <DisplayName> menggunakan sintaksis berikut:

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

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

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<OASResource>

Menentukan Spesifikasi OpenAPI yang akan divalidasi. Anda dapat menyimpan file ini:

• Di cakupan proxy API di bagian /apiproxy/resources/oas dalam paket proxy API
• Di bagian Resources pada tampilan Navigator editor proxy API.

Untuk mengetahui informasi selengkapnya, lihat Mengelola fasilitas.

Anda dapat menentukan Spesifikasi OpenAPI menggunakan template pesan, seperti {oas.resource.url}. Dalam hal ini, nilai variabel alur oas.resource.url (dalam tanda kurung kurawal) akan dievaluasi dan diganti ke dalam string payload saat runtime. Untuk mengetahui informasi selengkapnya, lihat Template pesan.

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

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

Elemen <OASResource> tidak memiliki atribut atau elemen turunan.

<Options>

Mengonfigurasi opsi untuk kebijakan.

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

Menentukan apakah kebijakan harus memvalidasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Tetapkan ke true untuk memvalidasi isi pesan. Disetel ke false untuk memvalidasi hanya apakah isi pesan ada.

Anda dapat mengontrol apakah eksekusi alur berlanjut setelah terjadi error validasi dengan menetapkan atribut continueOnError untuk elemen <OASValidation> ke 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>

Mengonfigurasi perilaku kebijakan jika ada parameter header, kueri, atau cookie dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<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> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter header dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter header ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

<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> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter kueri dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

<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> (turunan dari <AllowUnspecifiedParameters>)

Mengonfigurasi perilaku kebijakan jika ada parameter cookie dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

Untuk mengizinkan parameter cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI, tetapkan parameter ini ke true. Jika tidak, tetapkan parameter ini ke false agar eksekusi kebijakan gagal.

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

Pesan JSON yang akan dievaluasi terhadap serangan payload JSON. Setelan ini biasanya ditetapkan ke request, karena Anda biasanya perlu mengevaluasi permintaan masuk dari aplikasi klien. Setel ke response untuk mengevaluasi pesan respons. Disetel ke message untuk mengevaluasi pesan permintaan secara otomatis saat kebijakan dilampirkan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke alur respons.

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

Elemen <Source> tidak memiliki atribut atau elemen turunan.

Skema untuk kebijakan ini

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Kode error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Variabel error

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Fitur Spesifikasi OpenAPI yang didukung

Kebijakan OASValidation mendukung fitur Spesifikasi OpenAPI yang diringkas dalam tabel berikut, menurut kategori. Fitur yang tidak didukung juga dicantumkan.

Menggunakan pola dalam skema

Standar Spesifikasi OpenAPI memungkinkan spesifikasi menetapkan schema untuk menjelaskan jenis data parameter atau kolom. Untuk parameter atau kolom jenis string, skema juga dapat menentukan pattern, yang merupakan ekspresi reguler (regex) yang menentukan bentuk yang valid untuk string.

Sebagai contoh, perhatikan fragmen Spesifikasi OpenAPI berikut:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

Spesifikasi ini mengharuskan untuk operasi getProduct, parameter product-id harus mematuhi ekspresi reguler yang diberikan, yang menetapkan urutan 3 karakter kata, tanda hubung, dan 4 digit desimal.

Spesifikasi OpenAPI mengacu pada standar Validasi Skema JSON untuk secara formal menentukan perilaku pola dalam memvalidasi nilai string, dan pada standar Inti Skema JSON untuk rekomendasi kepada penulis skema terkait kumpulan sintaksis ekspresi reguler yang dibatasi. Standar tersebut merekomendasikan untuk menghindari penggunaan lookaround (lookahead dan lookbehind), backreference, dan ekspresi karakter oktal, di antara fitur lainnya, dalam pola di dalam dokumen Spesifikasi OpenAPI.

Secara default, Apigee memvalidasi dokumen Spesifikasi OpenAPI yang dirujuk oleh kebijakan OASValidation dan melaporkan error jika dokumen spesifikasi tidak dibuat dengan baik. Apigee juga memvalidasi pola regex dalam dokumen spesifikasi Anda dan melaporkan masalah yang ditemukan di sana.

Penting untuk diperhatikan bahwa jika Anda menggunakan fitur regex di luar subset yang direkomendasikan, Apigee tidak akan memvalidasi regex dan akan menangguhkan validasi tambahan apa pun pada dokumen Spesifikasi OpenAPI Anda. Jika ada error dalam dokumen, atau dalam regex yang menggunakan fitur di luar subset yang direkomendasikan, atau jika fitur regex tidak didukung oleh runtime Apigee, error hanya akan terdeteksi saat runtime ketika kebijakan dijalankan.

Tabel berikut memberikan beberapa contoh.

Sebaiknya gunakan hanya subset fitur yang direkomendasikan dalam regex Anda untuk mencegah kegagalan runtime.

Topik terkait

• Kebijakan perlindungan Ancaman JSON
• Kebijakan SOAPMessageValidation