Kebijakan OASValidation

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Tentang kebijakan OASValidation

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

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

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

Konten apa yang divalidasi?

Tabel berikut meringkas konten pesan permintaan yang divalidasi oleh kebijakan OASValidation, berdasarkan komponen.

Komponen Minta validasi
{i>Basepath<i} Memvalidasi jalur dasar yang ditentukan oleh proxy API; mengabaikan jalur dasar yang ditentukan dalam Spesifikasi OpenAPI.
Jalur Memvalidasi bahwa jalur permintaan (dikurangi jalur dasar) cocok dengan salah satu pola jalur yang ditetapkan dalam Spesifikasi OpenAPI.
Kata Kerja Memvalidasi bahwa kata kerja didefinisikan untuk jalur dalam Spesifikasi OpenAPI.
Isi pesan permintaan
  • Memvalidasi keberadaan isi pesan dalam permintaan, jika diperlukan.
  • Secara opsional, memvalidasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Konfigurasikan opsi ini menggunakan <ValidateMessageBody>

Catatan: Kebijakan ini memvalidasi isi pesan permintaan terhadap Spesifikasi OpenAPI hanya jika Content-Type disetel ke application/json. Jika jenis konten tidak ditetapkan ke application/json, validasi isi pesan permintaan akan otomatis diteruskan (tanpa benar-benar memvalidasi konten).

Parameter
  • Memvalidasi bahwa parameter yang diperlukan ada dalam permintaan, termasuk parameter jalur, header, kueri, dan cookie.
  • Memvalidasi bahwa nilai parameter cocok dengan nilai yang ditetapkan dalam Spesifikasi OpenAPI.
  • Secara opsional, memvalidasi apakah ada parameter dalam permintaan yang tidak ditetapkan dalam Spesifikasi OpenAPI. Konfigurasikan opsi ini menggunakan <AllowUnspecifiedParameters>

Tabel berikut meringkas konten pesan respons yang divalidasi oleh kebijakan OASValidation, berdasarkan komponen.

Komponen Validasi jawaban
Jalur Memvalidasi bahwa jalur permintaan (dikurangi jalur dasar) cocok dengan salah satu pola jalur yang ditetapkan dalam Spesifikasi OpenAPI.
Kata Kerja Memvalidasi bahwa kata kerja didefinisikan untuk jalur dalam Spesifikasi OpenAPI.
Isi pesan respons
  • Memvalidasi keberadaan isi pesan dalam respons, jika diperlukan.
  • Memvalidasi bahwa header respons dalam Spesifikasi OpenAPI ada dalam pesan respons, dan bahwa nilai header respons cocok dengan skema.
  • Secara opsional, memvalidasi isi pesan terhadap skema isi respons operasi dalam Spesifikasi OpenAPI. Konfigurasikan opsi ini menggunakan <ValidateMessageBody>

Contoh

Contoh berikut menunjukkan beberapa cara penggunaan kebijakan OASValidation untuk memvalidasi pesan terhadap Spesifikasi OpenAPI 3.0.

Validasi pesan permintaan

Dalam contoh berikut, kebijakan myoaspolicy memvalidasi isi pesan permintaan terhadap skema isi pesan permintaan operasi yang ditentukan dalam Spesifikasi OpenAPI my-spec.json.

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

Jika isi pesan tidak sesuai dengan Spesifikasi OpenAPI, error policies.oasvalidation.Failed akan ditampilkan.

Validasi parameter

Contoh berikut mengonfigurasi kebijakan untuk gagal jika header, kueri, atau parameter cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

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

Nilai Default Lihat tab Kebijakan Default di bawah
Wajib? Wajib
Jenis Objek kompleks
Elemen Induk t/a
Elemen Turunan <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

Sintaksis

Elemen <OASValidation> menggunakan sintaksis berikut:

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

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan Validasi OAS ke alur di UI 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>

Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:

Atribut Default Wajib? Deskripsi
name T/A Wajib

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

continueOnError false Opsional Tetapkan ke "false" untuk menampilkan error saat kebijakan gagal. Hal ini wajar untuk sebagian besar kebijakan. Tetapkan ke "true" agar eksekusi flow berlanjut meskipun kebijakan gagal.
enabled benar Opsional Tetapkan ke "true" untuk menerapkan kebijakan. Tetapkan ke "false" untuk "menonaktifkan" kebijakan. Kebijakan ini tidak akan diterapkan meskipun tetap dilampirkan ke flow.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <OASValidation>.

<DisplayName>

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

Elemen <DisplayName> bersifat umum untuk semua kebijakan.

Nilai Default t/a
Wajib? Opsional. Jika Anda menghapus <DisplayName>, nilai atribut name kebijakan akan digunakan
Jenis String
Elemen Induk <PolicyElement>
Elemen Turunan Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaksis

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

Contoh

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

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

Untuk informasi lebih lanjut, lihat Mengelola resource.

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

Nilai Default Tidak ada
Wajib? Wajib
Jenis String
Elemen Induk <OASValidation>
Elemen Turunan Tidak ada

Sintaksis

Elemen <OASResource> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut merujuk ke spesifikasi my-spec.yaml yang disimpan di /apiproxy/resources/oas dalam paket proxy API:

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

Elemen <OASResource> tidak memiliki atribut atau elemen turunan.

<Opsi>

Mengonfigurasi opsi untuk kebijakan.

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <OASValidation>
Elemen Turunan <ValidateMessageBody>
<AllowUnspecifiedParameters>

Sintaksis

Elemen <Options> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengonfigurasi opsi untuk kebijakan. Setiap opsi dijelaskan secara lebih mendetail di bawah.

<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 konten isi pesan. Tetapkan ke false untuk memvalidasi hanya bahwa isi pesan ada.

Anda dapat mengontrol apakah eksekusi alur akan terus berlanjut setelah error validasi dengan menetapkan atribut continueOnError untuk elemen <OASValidation> ke true.

Nilai Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <Options>
Elemen Turunan Tidak ada

Sintaksis

Elemen <ValidateMessageBody> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut memungkinkan validasi konten isi pesan:

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

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <Options>
Elemen Turunan <Header>
<Query>
<Cookie>

Sintaksis

Elemen <AllowUnspecifiedParameters> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengonfigurasi kebijakan untuk gagal jika header, kueri, atau parameter cookie ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

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

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

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

Nilai Default true
Wajib? Boolean
Jenis Jenis kompleks
Elemen Induk <AllowUnspecifiedParameters>
Elemen Turunan Tidak ada

Sintaksis

Elemen <Header> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengonfigurasi kebijakan untuk gagal jika parameter header ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

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

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

Nilai Default true
Wajib? Boolean
Jenis Jenis kompleks
Elemen Induk <AllowUnspecifiedParameters>
Elemen Turunan Tidak ada

Sintaksis

Elemen <Query> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengonfigurasi kebijakan untuk gagal jika parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

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

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

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

Nilai Default true
Wajib? Boolean
Jenis Jenis kompleks
Elemen Induk <AllowUnspecifiedParameters>
Elemen Turunan Tidak ada

Sintaksis

Elemen <Cookie> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengonfigurasi kebijakan untuk gagal jika parameter kueri ditentukan dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI.

<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. Nilai ini paling sering ditetapkan ke request, karena Anda biasanya harus mengevaluasi permintaan masuk dari aplikasi klien. Setel ke response untuk mengevaluasi pesan respons. Setel ke message untuk mengevaluasi pesan permintaan secara otomatis ketika kebijakan dilampirkan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke alur respons.

Nilai Default minta
Wajib? Opsional
Jenis String
Elemen Induk <Source>
Elemen Turunan Tidak ada

Sintaksis

Elemen <Source> menggunakan sintaksis berikut:

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

Contoh

Contoh berikut mengevaluasi pesan permintaan secara otomatis saat kebijakan dilampirkan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke alur respons:

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

Elemen <Source> tidak memiliki atribut atau elemen turunan.

Skema

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

Kode error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab
steps.oasvalidation.Failed 500 Isi pesan permintaan tidak dapat divalidasi berdasarkan Spesifikasi OpenAPI yang diberikan.
steps.oasvalidation.SourceMessageNotAvailable 500

Variabel yang ditentukan dalam elemen <Source> kebijakan berada di luar cakupan atau tidak dapat diselesaikan.

steps.oasvalidation.NotMessageVariable 500

Elemen <Source> ditetapkan ke variabel yang bukan jenis message.

Error saat deployment

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

Nama error Penyebab
ResourceDoesNotExist Spesifikasi OpenAPI yang dirujuk dalam elemen <OASResource> tidak ada.
ResourceCompileFailed Spesifikasi OpenAPI yang disertakan dalam deployment berisi error yang mencegahnya dikompilasi. Hal ini secara umum menunjukkan bahwa spesifikasi tersebut bukan Spesifikasi OpenAPI 3.0 yang diformat dengan baik.
BadResourceURL Spesifikasi OpenAPI yang direferensikan dalam elemen <OASResource> tidak dapat diproses. Hal ini dapat terjadi jika file bukan file JSON atau YAML, atau URL file tidak ditentukan dengan benar.

Variabel kesalahan

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

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. oasvalidation.myoaspolicy.failed = true

Fitur Spesifikasi OpenAPI yang didukung

Kebijakan OASValidation mendukung fitur Spesifikasi OpenAPI yang dirangkum dalam tabel berikut, berdasarkan kategori. Fitur yang tidak didukung juga tercantum.

Kategori Didukung Tidak didukung
Format jenis data boolean
tanggal
tanggal-waktu
ganda
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
biner
byte
sandi
Objek diskriminator pemetaan
propertyName
T/A
Objek jenis media schema contoh
encoding
contoh
Objek operasi parameter
requestBody
responses
security (dukungan parsial)
callback
server tidak digunakan lagi
Objek parameter allowEmptyValue
in (query, header, path)
respons
yang diperlukan
skema
(deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Catatan: deepObject hanya mendukung parameter string; array dan objek bertingkat tidak didukung.
allowReserved
tidak digunakan lagi
contoh
contoh
konten
Objek jalur hapus
dapatkan
head
opsi
parameter
patch
post
put
trace
variabel
server
Minta objek isi application/json
application/hal+json
application/x-www-form-urlencoding (objek encoding tidak didukung)
content
wajib
application/xml
multipart/form-data
teks/biasa
teks/xml
Objek respons application/json
application/hal+json
application/x-www-form-urlcoded (objek encoding tidak didukung)
header
contents
link aplikasi/xml

teks/biasa
teks/xml
Objek respons default
Kode Status HTTP
T/A
Objek skema $ref
additionalProperties (khusus varian tanda boolean)
allOf (diabaikan jika additionalProperties adalah false)
salah satu
enum
















tidak digunakan lagi
contoh
readOnly
writeOnly
xml
Objek skema keamanan dalam (header, query) (diabaikan jika type adalah http)
nama
jenis (apiKey, http)
BearerFormat
alur
openIdConnectUrl
skema
Objek server URL
variabel
Beberapa definisi server

Topik terkait