Memvalidasi konten

BERLAKU UNTUK: Semua tingkatAN API Management

Kebijakan validate-content memvalidasi ukuran atau konten dari badan permintaan atau tanggapan terhadap satu atau beberapa skema yang didukung.

Tabel berikut menunjukkan format skema dan jenis konten permintaan atau respons yang didukung oleh kebijakan. Nilai jenis konten tidak peka huruf besar/kecil.

Format	Jenis konten
JSON	Contoh: application/json application/hal+json
XML	Contoh: application/xml
SOAP	Nilai yang diizinkan: application/soap+xml untuk SOAP 1.2 API text/xml untuk SOAP 1.1 API

Catatan

Ukuran maksimum skema API yang dapat digunakan oleh kebijakan validasi ini adalah 4 MB. Jika skema melebihi batas ini, kebijakan validasi akan mengembalikan kesalahan pada runtime. Untuk meningkatkannya, hubungi dukungan.

Konten apa yang divalidasi

Kebijakan memvalidasi konten berikut dalam permintaan atau respons terhadap skema:

• Kehadiran semua properti yang diperlukan.
• Ada atau tidak adanya properti tambahan, jika skema memiliki set bidang additionalProperties. Dapat ditimpa dengan allow-additional-properties atribut .
• Jenis semua properti. Misalnya, jika skema menentukan properti sebagai bilangan bulat, permintaan (atau respons) harus menyertakan bilangan bulat dan bukan jenis lainnya, seperti string.
• Format properti, jika ditentukan dalam skema - misalnya, regex (jika kata kunci pattern ditentukan), minimum untuk bilangan bulat, dan sebagainya.

Tip

Untuk contoh batasan pola regex yang dapat digunakan dalam skema, lihat Repositori Regex Validasi OWASP.

Catatan

Tetapkan elemen kebijakan dan elemen turunan dalam urutan yang disediakan dalam pernyataan kebijakan. Untuk membantu Anda mengonfigurasi kebijakan ini, portal menyediakan editor berbasis formulir berikut panduannya. Pelajari lebih lanjut cara mengatur atau mengedit kebijakan API Management.

Pernyataan kebijakan

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" />
</validate-content>

Atribut

Atribut	Deskripsi	Wajib diisi	Default
unspecified-content-type-action	Tindakan yang dilakukan untuk permintaan atau respons dengan tipe konten yang tidak ditentukan dalam skema API. Ekspresi kebijakan diizinkan.	Ya	T/A
max-size	Panjang maksimum isi permintaan atau respons dalam byte, dicentang ke header Content-Length. Jika isi permintaan atau isi respons dikompresi, nilai ini adalah panjang yang terdekompresi. Nilai maksimum yang diperbolehkan: 102.400 byte (100 KB). (Hubungi dukungan jika Anda perlu meningkatkan batas ini.) Ekspresi kebijakan diizinkan.	Ya	T/A
size-exceeded-action	Tindakan yang harus dilakukan untuk permintaan atau respons yang isinya melebihi ukuran yang ditentukan dalam max-size. Ekspresi kebijakan diizinkan.	Ya	T/A
errors-variable-name	Nama variabel di context.Variables untuk mencatat kesalahan validasi. Ekspresi kebijakan tidak diizinkan.	No	T/A

Elemen

Nama	Deskripsi	Wajib diisi
peta jenis konten	Tambahkan elemen ini untuk memetakan jenis konten dari permintaan atau respons yang masuk ke jenis konten lain yang digunakan untuk memicu validasi.	No
konten	Tambahkan satu atau beberapa elemen ini untuk memvalidasi jenis konten dalam permintaan atau respons, atau jenis konten yang dipetakan, dan lakukan tindakan yang ditentukan.	No

atribut peta jenis konten

Atribut	Deskripsi	Wajib diisi	Default
semua-konten-jenis-nilai	Jenis konten yang digunakan untuk validasi isi permintaan atau respons, terlepas dari jenis konten yang masuk. Ekspresi kebijakan tidak diizinkan.	No	T/A
nilai jenis konten yang hilang	Jenis konten yang digunakan untuk validasi isi permintaan atau respons, ketika jenis konten yang masuk tidak ada atau kosong. Ekspresi kebijakan tidak diizinkan.	No	T/A

elemen content-type-map

Nama	Deskripsi	Wajib
jenis	Tambahkan satu atau beberapa elemen ini untuk memetakan jenis konten yang masuk ke jenis konten yang digunakan untuk validasi isi permintaan atau respons. Gunakan from untuk menentukan jenis konten masuk yang diketahui, atau gunakan when dengan ekspresi kebijakan untuk menentukan jenis konten masuk apa pun yang cocok dengan kondisi. Mengganti pemetaan di any-content-type-value dan missing-content-type-value, jika ditentukan.	No

atribut konten

Atribut	Deskripsi	Wajib diisi	Default
jenis	Jenis konten untuk menjalankan validasi isi, diperiksa terhadap header jenis konten atau nilai yang dipetakan dalam content-type-mapping, jika ditentukan. Jika kosong, ini berlaku untuk setiap jenis konten yang ditentukan dalam skema API. Untuk memvalidasi permintaan dan tanggapan SOAP (validate-as atribut diatur ke "soap"), atur type ke application/soap+xml untuk SOAP 1.2 API atau text/xml untuk SOAP 1.1 API.	No	T/A
validate-as	Mesin validasi yang digunakan untuk validasi isi permintaan atau respons dengan type yang cocok. Nilai yang didukung: "json", "xml", "soap". Ketika "soap" ditentukan, XML dari permintaan atau respons diekstraksi dari amplop SOAP dan divalidasi terhadap skema XML.	Ya	T/A
schema-id	Nama skema yang ada yang ditambahkan ke instans API Management untuk validasi konten. Jika tidak ditentukan, skema default dari definisi API akan digunakan.	No	T/A
schema-ref	Untuk skema JSON yang ditentukan dalam schema-id, referensi opsional ke jalur referensi lokal yang valid di dokumen JSON. Contoh: #/components/schemas/address. Atribut harus mengembalikan objek JSON yang ditangani API Management sebagai skema JSON yang valid. Untuk skema XML, schema-ref tidak didukung, dan elemen skema tingkat atas apa pun dapat digunakan sebagai akar permintaan XML atau payload respons. Validasi memeriksa bahwa semua elemen mulai dari permintaan XML atau root payload respons mematuhi skema XML yang disediakan.	No	T/A
allow-additional-properties	Boolean. Untuk skema JSON, menentukan apakah akan menerapkan penimpaan runtime nilai yang additionalProperties dikonfigurasi dalam skema: - true: mengizinkan properti tambahan dalam isi permintaan atau respons, meskipun bidang additionalProperties skema JSON dikonfigurasi agar tidak mengizinkan properti tambahan. - false: tidak mengizinkan properti tambahan dalam isi permintaan atau respons, meskipun bidang additionalProperties skema JSON dikonfigurasi agar mengizinkan properti tambahan. Jika atribut tidak ditentukan, kebijakan memvalidasi properti tambahan sesuai dengan konfigurasi bidang additionalProperties dalam skema.	No	T/A

Tindakan

Kebijakan validasi konten mencakup satu atau beberapa atribut yang menentukan tindakan, yang diambil API Management saat memvalidasi entitas dalam permintaan API atau respons terhadap skema API.

• Tindakan dapat ditentukan untuk elemen yang diwakili dalam skema API dan, tergantung pada kebijakan, untuk elemen yang tidak diwakili dalam skema API.

• Tindakan yang ditentukan dalam elemen anak kebijakan akan menggantikan tindakan yang ditentukan untuk induknya.

Tindakan yang tersedia:

Tindakan	Deskripsi
abaikan	Lewati validasi.
cegah	Blokir permintaan atau pemrosesan respons, catat kesalahan validasi verbose, dan tampilkan kesalahan. Pemrosesan terganggu ketika serangkaian kesalahan pertama terdeteksi.
deteksi	Catat kesalahan validasi, tanpa mengganggu pemrosesan permintaan atau respons.

Penggunaan

• Bagian kebijakan: masuk, keluar, saat terjadi kesalahan
• Cakupan kebijakan: global, ruang kerja, produk, API, operasi
• Gateway: klasik, v2, konsumsi, dihost sendiri

Log

Detail tentang kesalahan validasi selama eksekusi kebijakan dicatat ke variabel di context.Variables yang ditentukan dalam atribut errors-variable-name dalam elemen akar kebijakan. Saat dikonfigurasi dalam tindakan prevent, kesalahan validasi memblokir permintaan atau pemrosesan respons lebih lanjut dan juga disebarluaskan ke properti context.LastError.

Untuk menyelidiki kesalahan, gunakan kebijakan pelacakan untuk mencatat kesalahan dari variabel konteks ke Wawasan Aplikasi.

Implikasi kinerja

Menambahkan kebijakan validasi dapat memengaruhi throughput API. Prinsip umum berikut ini berlaku:

• Semakin besar ukuran skema API, semakin rendah throughputnya.
• Semakin besar muatan dalam permintaan atau respons, semakin rendah throughputnya.
• Ukuran skema API memiliki dampak yang lebih besar pada performa daripada ukuran muatan.
• Validasi terhadap skema API yang berukuran beberapa megabyte dapat menyebabkan waktu permintaan atau respons habis dalam beberapa kondisi. Efeknya lebih terasa di tingkat Konsumsi dan Pengembang layanan.

Sebaiknya lakukan uji beban dengan beban kerja produksi yang diharapkan untuk menilai dampak kebijakan validasi pada throughput API.

Skema untuk validasi konten

Secara default, validasi konten permintaan atau respons menggunakan skema JSON atau XML dari definisi API. Skema ini dapat ditentukan secara manual atau dibuat secara otomatis saat mengimpor API dari spesifikasi OpenAPI atau WSDL ke API Management.

Dengan menggunakan kebijakan validate-content, Anda dapat memvalidasi secara opsional terhadap satu atau beberapa skema JSON atau XML yang telah Anda tambahkan ke instans API Management dan yang bukan bagian dari definisi API. Skema yang Anda tambahkan ke API Management dapat digunakan kembali di banyak API.

Untuk menambahkan skema ke instans API Management Anda menggunakan portal Azure:

1. Di portal, navigasikan ke instans API Management Anda.

2. Di bagian API di menu sebelah kiri, pilih Skema>+ Tambahkan.

3. Di jendela Buat skema, lakukan hal berikut:

   1. Masukkan Nama (ID) untuk skema.
   2. Dalam Jenis skema, pilih JSON atau XML.
   3. Masukkan Deskripsi.
   4. Di Buat metode, lakukan salah satu hal berikut ini:
      • Pilih Buat baru dan masukkan atau tempel skema.
      • Pilih Impor dari file atau Impor dari URL dan masukkan lokasi skema.

        Catatan

        Untuk mengimpor skema dari URL, skema harus dapat diakses melalui internet dari browser.

   5. Pilih Simpan.

   

API Management menambahkan sumber daya skema di URI /schemas/<schemaId> relatif, dan skema muncul dalam daftar di halaman Skema. Pilih skema untuk melihat propertinya atau untuk diedit di editor skema.

Catatan

Skema dapat mereferensikan silang skema lain yang ditambahkan ke instans API Management. Misalnya, sertakan skema XML yang ditambahkan ke API Management dengan menggunakan elemen yang mirip dengan:

<xs:include schemaLocation="/schemas/myschema" />

Tip

Alat sumber terbuka untuk menyelesaikan referensi skema WSDL dan XSD dan untuk mengimpor batch skema yang dihasilkan ke API Management tersedia di GitHub.

Contoh

Validasi skema JSON

Dalam contoh berikut, API Management menginterpretasikan permintaan dengan header jenis konten kosong atau permintaan dengan header jenis konten application/hal+json sebagai permintaan dengan jenis konten application/json. Kemudian, API Management melakukan validasi dalam mode deteksi terhadap skema yang ditentukan untuk jenis konten application/json dalam definisi API. Pesan dengan muatan yang lebih besar dari 100 KB diblokir. Permintaan yang berisi properti tambahan diblokir, meskipun bidang additionalProperties skema dikonfigurasi untuk memungkinkan properti tambahan.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

Validasi skema SOAP

Dalam contoh berikut, API Management menginterpretasikan permintaan apa pun sebagai permintaan dengan jenis konten application/soap+xml (jenis konten yang digunakan oleh SOAP 1.2 API), terlepas dari jenis konten yang masuk. Permintaan dapat datang dengan header jenis konten kosong, header jenis konten text/xml (digunakan oleh SOAP 1.1 API), atau header jenis konten lainnya. Kemudian, API Management mengekstrak muatan XML dari amplop SOAP dan melakukan validasi dalam mode pencegahan terhadap skema bernama "myschema". Pesan dengan muatan yang lebih besar dari 100 KB diblokir.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

Kesalahan validasi

API Management menghasilkan kesalahan validasi konten dalam format berikut:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

Tabel berikut ini mencantumkan semua kemungkinan kesalahan kebijakan validasi.

• Detail: Dapat digunakan untuk menyelidiki kesalahan. Tidak dimaksudkan untuk dibagikan ke publik.
• Respons publik: Kesalahan yang ditampilkan ke klien. Tidak membocorkan detail implementasi.

Saat kebijakan validasi menentukan tindakan prevent dan menghasilkan kesalahan, respons dari manajemen API menyertakan kode status HTTP: 400 saat kebijakan diterapkan di bagian masuk, dan 502 saat kebijakan diterapkan di bagian keluar.

Nama	Jenis	Aturan validasi	Rincian	Respons publik	Perbuatan
validate-content
	RequestBody	SizeLimit	Isi permintaan panjangnya {size} byte dan melebihi batas konfigurasi {maxSize} byte.	Isi permintaan panjangnya {size} byte dan melebihi batas {maxSize} byte.	deteksi / cegah
	ResponseBody	SizeLimit	Isi respons panjangnya {size} byte dan melebihi batas konfigurasi {maxSize} byte.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{messageContentType}	RequestBody	Tidak disebutkan	Tipe konten yang tidak ditentukan {messageContentType} tidak diizinkan.	Tipe konten yang tidak ditentukan {messageContentType} tidak diizinkan.	deteksi / cegah
{messageContentType}	ResponseBody	Tidak disebutkan	Tipe konten yang tidak ditentukan {messageContentType} tidak diizinkan.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	ApiSchema		Skema API tidak ada atau tidak dapat diselesaikan.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	ApiSchema		Skema API tidak menentukan definisi.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	Skema API tidak berisi definisi {definitionName}, yang dikaitkan dengan jenis konten {messageContentType}.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{messageContentType}	RequestBody	IncorrectMessage	Isi permintaan tidak sesuai dengan definisi {definitionName}, yang dikaitkan dengan jenis konten {messageContentType}. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	Isi permintaan tidak sesuai dengan definisi {definitionName}, yang dikaitkan dengan jenis konten {messageContentType}. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	deteksi / cegah
{messageContentType}	ResponseBody	IncorrectMessage	Isi respons tidak sesuai dengan definisi {definitionName}, yang dikaitkan dengan jenis konten {messageContentType}. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	RequestBody	ValidationException	Isi permintaan tidak dapat divalidasi untuk jenis konten {messageContentType}. {exception details}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	ResponseBody	ValidationException	Isi respons tidak dapat divalidasi untuk jenis konten {messageContentType}. {exception details}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	Tidak disebutkan	{path parameter / query parameter / header} {paramName} yang tidak ditetapkan tidak diizinkan.	{path parameter / query parameter / header} {paramName} yang tidak ditetapkan tidak diizinkan.	deteksi / cegah
{headerName}	ResponseHeader	Tidak disebutkan	Header {headerName} yang tidak ditentukan tidak diperbolehkan.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	ApiSchema		Skema API tidak ada atau tidak dapat diselesaikan.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
	ApiSchema		Skema API tidak menentukan definisi.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	Skema API tidak berisi definisi {definitionName}, yang dikaitkan dengan parameter {query parameter / path parameter / header} {paramName}.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	Permintaan tidak boleh berisi beberapa nilai untuk {query parameter / path parameter / header} {paramName}.	Permintaan tidak boleh berisi beberapa nilai untuk {query parameter / path parameter / header} {paramName}.	deteksi / cegah
{headerName}	ResponseHeader	IncorrectMessage	Respons tidak boleh berisi beberapa nilai untuk header {headerName}.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	Nilai {query parameter / path parameter / header} {paramName} tidak sesuai dengan definisi. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	Nilai {query parameter / path parameter / header} {paramName} tidak sesuai dengan definisi. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	deteksi / cegah
{headerName}	ResponseHeader	IncorrectMessage	Nilai header {headerName} tidak sesuai dengan definisi. {valError.Message} Baris: {valError.LineNumber}, Posisi: {valError.LinePosition}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	Nilai {query parameter / path parameter / header} {paramName} tidak dapat diuraikan berdasarkan defisini. {ex.Message}	Nilai {query parameter / path parameter / header} {paramName} tidak dapat diuraikan berdasarkan defisini. {ex.Message}	deteksi / cegah
{headerName}	ResponseHeader	IncorrectMessage	Nilai header {headerName} tidak dapat diuraikan berdasarkan defisini.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{paramName}	QueryParameter / PathParameter / RequestHeader	ValidationError	{Query parameter / Path parameter / Header} {paramName} tidak dapat divalidasi. {exception details}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
{headerName}	ResponseHeader	ValidationError	Header {headerName} tidak dapat divalidasi. {exception details}	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah
validate-status-code
{status-code}	StatusCode	Tidak disebutkan	Kode status respons {status-code} tidak diperbolehkan.	Permintaan tidak dapat diproses karena kesalahan layanan internal. Hubungi pemilik API.	deteksi / cegah

Tabel berikut ini mencantumkan semua nilai Alasan yang mungkin dari kesalahan validasi bersama dengan nilai Pesan yang mungkin:

Alasan	Pesan
Permintaan Buruk	{Details} untuk variabel konteks, {Public response} untuk klien
Respons tidak diperbolehkan	{Details} untuk variabel konteks, {Public response} untuk klien

Kebijakan terkait

• Validasi konten

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat:

• Tutorial: Mengubah dan melindungi API Anda
• Referensi Kebijakan untuk daftar lengkap pernyataan kebijakan dan pengaturannya
• Ekspresi kebijakan
• Mengatur atau mengedit kebijakan
• Menggunakan kembali konfigurasi kebijakan
• Repositori cuplikan kebijakan
• Kebijakan penulis menggunakan Microsoft Copilot untuk Azure