Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Tentang kebijakan OASValidation
Kebijakan OASValidation (Validasi Spesifikasi OpenAPI) memungkinkan Anda memvalidasi permintaan atau pesan respons 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 dipasangi 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
.
Menambahkan 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 |
---|---|
Jalur dasar | Memvalidasi jalur dasar yang ditentukan oleh proxy API; mengabaikan jalur dasar yang ditetapkan dalam Spesifikasi OpenAPI. |
Jalur | Memvalidasi bahwa jalur permintaan (tanpa jalur basis) cocok dengan salah satu pola jalur yang ditentukan dalam Spesifikasi OpenAPI. |
Kata kerja | Memvalidasi bahwa kata kerja ditentukan untuk jalur dalam Spesifikasi OpenAPI. |
Isi pesan permintaan |
Catatan: Kebijakan ini memvalidasi isi pesan permintaan berdasarkan Spesifikasi OpenAPI hanya jika Content-Type disetel ke
|
Parameter |
|
Tabel berikut meringkas konten pesan respons yang divalidasi oleh kebijakan OASValidation, berdasarkan komponen.
Komponen | Validasi respons |
---|---|
Jalur | Memvalidasi bahwa jalur permintaan (tanpa jalur basis) cocok dengan salah satu pola jalur yang ditentukan dalam Spesifikasi OpenAPI. |
Kata kerja | Memvalidasi bahwa kata kerja ditentukan untuk jalur dalam Spesifikasi OpenAPI. |
Isi pesan respons |
|
Contoh
Contoh berikut menunjukkan beberapa cara menggunakan OASValidation kebijakan untuk memvalidasi pesan terhadap Spesifikasi OpenAPI 3.0.
Validasi pesan permintaan
Pada 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 agar gagal jika parameter header, kueri, atau cookie ditentukan dalam permintaan yang tidak yang 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 Anda 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 Secara opsional, gunakan elemen |
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 dari <OASValidation>
.
<DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
baru dengan nama yang berbeda dan terdengar lebih alami.
Elemen <DisplayName>
umum untuk semua kebijakan.
Nilai Default | t/a |
Wajib? | Opsional. Jika Anda menghapus <DisplayName> , nilai atribut
atribut name kebijakan 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 mengetahui informasi selengkapnya, 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 ke dalam 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 pada 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.
<Options>
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 tersebut. Setiap opsi dijelaskan secara lebih mendetail di bawah ini.
<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. Tetapkan ke false untuk memvalidasi hanya bahwa isi pesan ada.
Anda dapat mengontrol apakah eksekusi alur akan terus berlanjut setelah terjadi error validasi dengan menyetel atribut continueOnError
untuk <OASValidation>
ke true.
Nilai Default | salah |
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 isi 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 ada dalam permintaan yang tidak didefinisikan 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 agar gagal jika parameter header, kueri, atau cookie ditentukan dalam permintaan yang tidak yang 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>
<Header>
(turunan <AllowUnspecifiedParameters>
)
Mengonfigurasi perilaku kebijakan jika ada parameter header ada dalam permintaan yang tidak didefinisikan 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.
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 agar gagal jika parameter header ditentukan dalam permintaan yang tidak yang ditentukan dalam Spesifikasi OpenAPI.
<OASValidation name="myoaspolicy"> <OASResource>oas://my-spec.yaml</OASResource> <Options> <AllowUnspecifiedParameters> <Header>false</Header> </AllowUnspecifiedParameters> </Options> </OASValidation>
<Query>
(turunan <AllowUnspecifiedParameters>
)
Mengonfigurasi perilaku kebijakan jika ada parameter kueri ada dalam permintaan yang tidak didefinisikan dalam Spesifikasi OpenAPI.
Untuk memungkinkan 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.
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 agar gagal jika parameter kueri ditentukan dalam permintaan yang tidak yang 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 ada dalam permintaan yang tidak didefinisikan 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.
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 agar gagal jika parameter kueri ditentukan dalam permintaan yang tidak yang 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. Fungsi ini paling sering disetel ke
request
, karena Anda biasanya perlu mengevaluasi permintaan masuk dari aplikasi klien.
Tetapkan ke response untuk mengevaluasi pesan respons.
Tetapkan ke message untuk mengevaluasi pesan permintaan secara otomatis
kapan kebijakan disertakan ke alur permintaan dan pesan respons saat kebijakan dilampirkan ke respons
alur kerja.
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 secara otomatis pesan permintaan 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
). Sebagai 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 |
|
steps.oasvalidation.NotMessageVariable |
500 |
Elemen |
build |
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. Beberapa fitur yang tidak didukung juga dicantumkan.
Kategori | Didukung | Tidak didukung |
---|---|---|
Format jenis data | boolean tanggal tanggal-waktu ganda mengambang 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 | encoding contoh contoh |
Objek operasi | parameter requestBody jawaban keamanan (dukungan sebagian) |
callback tidak digunakan lagi server |
Objek Parameters | allowEmptyValue dalam ( query , header , path )wajib jawaban skema gaya ( 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 kepala opsi parameter patch postingan setel rekaman aktivitas variabel |
server |
Minta objek isi | application/json application/hal+json application/x-www-form-urlencoding (objek encoding tidak didukung)konten wajib diisi |
aplikasi/xml multibagian/formulir-data teks/biasa teks/xml |
Objek respons | application/json application/hal+json application/x-www-form-urlencoding (objek encoding tidak didukung)konten header |
aplikasi/xml tautan 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 )anyOf enum exclusiveMaximum/exclusiveMinimum format item maksimum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf bukan nullable oneOf pola properti wajib judul jenis uniqueItems |
tidak digunakan lagi contoh readOnly writeOnly XML |
Objek skema keamanan | di (header , query ) (diabaikan jika type adalah http )nama jenis ( apiKey , http )
|
bearerFormat alur openIdConnectUrl skema |
Objek server | url variabel |
Definisi beberapa server |