Kebijakan OASValidation

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

Tentang kebijakan OASValidation

Kebijakan OASValidation (Validasi Spesifikasi OpenAPI) memungkinkan Anda memvalidasi permintaan yang masuk atau pesan respons 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 terkait dengan 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 merangkum konten pesan permintaan yang divalidasi oleh kebijakan OASValidation, menurut komponen.

Komponen Minta validasi
Basepath Memvalidasi basepath yang ditentukan oleh proxy API; mengabaikan basepath yang ditentukan dalam Spesifikasi OpenAPI.
Jalur Memvalidasi bahwa jalur permintaan (tanpa basepath) 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, memvalidasi isi pesan terhadap skema isi permintaan operasi dalam Spesifikasi OpenAPI. Konfigurasi 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 disetel ke application/json, validasi isi pesan permintaan akan lulus 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 yang ditentukan dalam Spesifikasi OpenAPI.
  • Secara opsional, memvalidasi apakah ada parameter dalam permintaan yang tidak ditentukan dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <AllowUnspecifiedParameters>

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

Komponen Validasi respons
Jalur Memvalidasi bahwa jalur permintaan (tanpa basepath) 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 nilai header respons cocok dengan skema.
  • Secara opsional, memvalidasi isi pesan terhadap skema isi respons operasi dalam Spesifikasi OpenAPI. Konfigurasi opsi ini menggunakan <ValidateMessageBody>

Contoh

Contoh berikut menunjukkan beberapa cara Anda dapat menggunakan kebijakan OASValidation untuk memvalidasi pesan terhadap Spesifikasi OpenAPI 3.0.

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

Memvalidasi parameter

Contoh berikut mengonfigurasi kebijakan agar gagal jika parameter header, kueri, atau 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>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <OASValidation>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

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

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.

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 mereferensikan 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. Setiap opsi dijelaskan 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 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.

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 mengaktifkan 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 agar gagal jika parameter header, kueri, atau 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.

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

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.

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

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

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). Sebagai referensi, skema kebijakan tersedia di GitHub.

Kode error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.oasvalidation.Failed 500 Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable 500

Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NotMessageVariable 500

<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
ResourceDoesNotExist OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oasvalidation.myoaspolicy.failed = true

Fitur Spesifikasi OpenAPI yang didukung

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

Kategori Didukung Tidak didukung
Format jenis data boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 biner
byte
sandi
Objek diskriminator mapping
propertyName 		T/A
Objek jenis media schema encoding
contoh
contoh
Objek operasi parameters
requestBody
responses
security (dukungan sebagian) 		callback
tidak digunakan lagi
server
Objek parameter allowEmptyValue
in (query, header, path)
required
responses
schema
style (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 delete
get
head
options
parameters
patch
post
put
trace
variables 		server
Objek isi permintaan application/json
application/hal+json
application/x-www-form-urlencoded (objek encoding tidak didukung)
content
required 		application/xml
multipart/form-data
text/plain
text/xml
Objek respons application/json
application/hal+json
application/x-www-form-urlencoded (objek encoding tidak didukung)
content
headers 		application/xml
links
text/plain
text/xml
Objek respons default
Kode Status HTTP 		T/A
Objek skema $ref
additionalProperties (hanya varian tanda boolean)
allOf (diabaikan jika additionalProperties adalah false)
anyOf
enum
exclusiveMaximum/exclusiveMinimum
format
items
maximum/minimum
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
properties
required
title
type
uniqueItems 		tidak digunakan lagi
contoh
hanyaBaca
hanyaTulis
xml
Objek skema keamanan in (header, query) (diabaikan jika type adalah http)
name
type (apiKey, http) 		bearerFormat
flows
openIdConnectUrl
scheme
Objek server url
variables 		Beberapa definisi server

Topik terkait