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 pesan permintaan atau respons terhadap sebuah OpenAPI 3.0 Spesifikasi, menggunakan format 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. Dokumen Spesifikasi OpenAPI harus memiliki ekstensi .json, .yml, atau .yaml.

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

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua perlu diketahui pengguna tentang jenis kebijakan dan lingkungan. Sebagai informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

Catatan: Anda dapat menyimpan Spesifikasi OpenAPI dengan revisi proxy API saja. Lihat Tempat resource disimpan.

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	Memvalidasi keberadaan isi pesan dalam permintaan, jika diperlukan. Secara opsional, validasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <ValidateMessageBody> Catatan: Kebijakan ini memvalidasi isi pesan permintaan berdasarkan Spesifikasi OpenAPI hanya jika Content-Type disetel ke application/json. Jika jenis konten tidak disetel ke application/json, validasi isi pesan permintaan akan diteruskan secara otomatis (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 ditentukan dalam Spesifikasi OpenAPI. Secara opsional, memvalidasi apakah parameter ada dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <AllowUnspecifiedParameters>

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	Memvalidasi keberadaan isi pesan dalam respons, jika diperlukan. Memvalidasi bahwa header respons dalam Spesifikasi OpenAPI ada dalam pesan respons, dan bahwa nilai respons {i>header <i}cocok dengan skema. Secara opsional, validasi isi pesan terhadap skema isi respons operasi dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <ValidateMessageBody>

Sampel

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>

Sintaks

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 name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
continueOnError	false	Opsional	Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani kesalahan dalam alur saat ini
enabled	true	Opsional	Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async	false	Tidak digunakan lagi	Atribut ini sudah tidak digunakan lagi.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan dari <OASValidation>.

<DisplayName>

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

Elemen <DisplayName> bersifat umum untuk semua kebijakan.

Nilai Default	T/A
Wajib?	Opsional. Jika Anda menghilangkan <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 mengetahui informasi selengkapnya, lihat Mengelola fasilitas.

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

Sintaks

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.

Catatan: Jika kebijakan OASValidation menentukan <OASResource> dengan persyaratan keamanan yang ditetapkan di tingkat global, persyaratan keamanan tidak diterapkan. Untuk memastikan penerapannya, semua persyaratan keamanan harus disetel di level operation dalam spesifikasi OpenAPI yang diteruskan dalam elemen <OASResource> kebijakan ini. Untuk informasi selengkapnya, lihat Masalah Umum Apigee.

&lt;Options&gt;

Mengonfigurasi opsi untuk kebijakan.

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

Sintaks

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>

&lt;ValidateMessageBody&gt;

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.

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

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

Sintaks

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>

Sintaks

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	benar
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaks

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	benar
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaks

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>

<Cookie> (turunan <AllowUnspecifiedParameters>)

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	benar
Wajib?	Boolean
Jenis	Jenis kompleks
Elemen Induk	<AllowUnspecifiedParameters>
Elemen Turunan	Tidak ada

Sintaks

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	permintaan
Wajib?	Opsional
Jenis	String
Elemen Induk	<Source>
Elemen Turunan	Tidak ada

Sintaks

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 untuk kebijakan ini

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 Apigee 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	400	Isi pesan Permintaan tidak dapat divalidasi berdasarkan Spesifikasi OpenAPI yang diberikan.
steps.oasvalidation.Failed	500	Isi pesan Response tidak dapat divalidasi dengan 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.NonMessageVariable	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	Deskripsi	Contoh
fault.category	Kategori kesalahan. Jika kebijakan menolak permintaan, Step akan selalu ditahan.	fault.category = "Step"
fault.name	Nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan.	fault.name Matches "ResourceDoesNotExist"
fault.reason	Alasan kesalahan. Ini adalah string yang dapat dibaca manusia yang menjelaskan alasan kesalahan.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	Subkategori kesalahan. Jika kebijakan menolak permintaan, OASValidationFailure akan selalu ditahan.	fault.subcategory = "OASValidationFailure"
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.

Catatan: Kebijakan OASValidation akan menolak Spesifikasi OpenAPI yang menggunakan fitur yang tidak didukung. Dalam hal ini, kebijakan tidak akan lulus validasi fitur yang tidak didukung dan deployment proxy API gagal.

Kategori	Didukung	Tidak didukung
Format jenis data	boolean tanggal tanggal-waktu ganda email 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

Menggunakan pola dalam skema

Standar Spesifikasi OpenAPI memungkinkan spesifikasi menetapkan schema untuk mendeskripsikan tipe data parameter atau kolom. Untuk parameter atau kolom dari string jenis, 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 parameter product-id untuk operasi getProduct sesuai dengan diberikan ekspresi reguler, yang menetapkan urutan 3 karakter kata, tanda hubung, dan 4 digit desimal.

Spesifikasi OpenAPI menunda ke standar Validasi Skema JSON untuk secara formal mendefinisikan perilaku pola dalam memvalidasi nilai string, dan Standar JSON Schema Core untuk mendapatkan rekomendasi bagi penulis skema terkait kumpulan sintaksis ekspresi reguler yang dibatasi. Terakhir, standar merekomendasikan untuk menghindari penggunaan lihat-lihat (lihat depan dan belakang), referensi belakang, dan oktal ekspresi karakter, 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 dibentuk dengan baik. Apigee juga memvalidasi pola ekspresi reguler dalam dokumen spesifikasi Anda dan melaporkan masalah yang ditemukan di sana.

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

Tabel berikut memberikan beberapa contoh.

Pola	Perilaku
^\w{3}-\d{4}$	Pola ini valid. Pengujian ini hanya menggunakan fitur ekspresi reguler dalam subset yang direkomendasikan. Apigee akan mengizinkan penyimpanan atau impor proxy, dan pada saat runtime kebijakan OASValidation akan berfungsi sebagaimana mestinya, memvalidasi parameter terhadap pola.
^([a-z]\w{3}-\d{4}$	Polanya tidak valid; tidak ada tanda kurung penutup. Pola ini tidak menggunakan fitur ekspresi reguler di luar subset yang direkomendasikan. Apigee akan melaporkan error ini pada saat Anda mengimpor atau menyimpan proxy API.
^(?![a-z]\w{3}-\d{4}$	Pola tidak valid. Seperti contoh sebelumnya, tanda kurung penutup tidak ada. Namun, Apigee tidak akan melaporkan error ini saat Anda menyimpan atau mengimpor Proxy API, karena ekspresi reguler menggunakan sudut pandang negatif, yang berada di luar subset yang direkomendasikan fitur ekspresi reguler. Error hanya akan terdeteksi saat runtime jika kebijakan akan dijalankan.
^(?![a-z])\w{3}-\d{4}$	Pola tersebut valid, namun menggunakan pola lihat negatif, yang berada di luar subkumpulan fitur ekspresi reguler yang direkomendasikan. Apigee akan menangguhkan validasi OpenAPI Dokumen spesifikasi. Saat runtime, ketika Anda menjalankan kebijakan OASValidation yang merujuk pada spesifikasi menggunakan pola ini, karena runtime Apigee sebenarnya mendukung pandangan negatif, Apigee akan menerapkan ekspresi reguler ini dengan benar untuk memvalidasi nilai parameter.
^(a)?b(?(1)c|d)$	Pola ini valid, tetapi menggunakan kondisional grup tangkapan, yang berada di luar subkumpulan fitur ekspresi reguler yang direkomendasikan. Apigee akan menangguhkan validasi OpenAPI Dokumen spesifikasi. Saat runtime, ketika Anda menjalankan kebijakan OASValidation yang merujuk pada spesifikasi menggunakan pola ini, karena runtime Apigee tidak mendukung fitur ekspresi reguler ini, Apigee akan menampilkan error.

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

Topik terkait

• Ancaman JSON Kebijakan perlindungan
• Kebijakan SOAPMessageValidation