Validasi parameter
BERLAKU UNTUK: Semua tingkatAN API Management
Kebijakan validate-parameters memvalidasi parameter header, kueri, atau path dalam permintaan terhadap skema API.
Penting
Jika Anda mengimpor API menggunakan versi API manajemen sebelum 2021-01-01-preview, kebijakan validate-parameters mungkin tidak berfungsi. Anda mungkin perlu mengimpor ulang API Anda menggunakan versi API manajemen 2021-01-01-preview atau yang lebih baru.
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.
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-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name">
<headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
<parameter name="parameter name" action="ignore | prevent | detect" />
</headers>
<query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
<parameter name="parameter name" action="ignore | prevent | detect" />
</query>
<path specified-parameter-action="ignore | prevent | detect">
<parameter name="parameter name" action="ignore | prevent | detect" />
</path>
</validate-parameters>
Atribut
| Atribut | Deskripsi | Wajib diisi | Default |
|---|---|---|---|
| specified-parameter-action | Tindakan yang harus dilakukan untuk parameter permintaan yang ditentukan dalam skema API. Saat disediakan di elemen headers, query, atau path, nilai akan menggantikan nilai dalam specified-parameter-action dalam elemen validate-parameters. Ekspresi kebijakan diizinkan. |
Ya | T/A |
| unspecified-parameter-action | Tindakan yang harus dilakukan untuk parameter permintaan yang tidak ditentukan dalam skema API. Saat disediakan di elemen headers atau query, nilai akan menggantikan nilai unspecified-parameter-action dalam elemen validate-parameters. 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 |
|---|---|---|
| header | Tambahkan elemen ini dan satu atau beberapa parameter sublemen untuk mengambil alih tindakan validasi default untuk parameter bernama tertentu dalam permintaan. Jika parameter ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi specified-parameter-action dengan level yang lebih tinggi. Jika parameter tidak ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi unspecified-parameter-action dengan level yang lebih tinggi. |
No |
| pertanyaan | Tambahkan elemen ini dan satu atau beberapa parameter sublemen untuk mengambil alih tindakan validasi default untuk parameter kueri bernama tertentu dalam permintaan. Jika parameter ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi specified-parameter-action dengan level yang lebih tinggi. Jika parameter tidak ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi unspecified-parameter-action dengan level yang lebih tinggi. |
No |
| jalan | Tambahkan elemen ini dan satu atau beberapa parameter sublemen untuk mengambil alih tindakan validasi default untuk parameter jalur URL tertentu dalam permintaan. Jika parameter ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi specified-parameter-action dengan level yang lebih tinggi. Jika parameter tidak ditentukan dalam skema API, nilai ini akan menggantikan konfigurasi unspecified-parameter-action dengan level yang lebih tinggi. |
No |
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
- Cakupan kebijakan: global, ruang kerja, produk, API, operasi
- Gateway: klasik, v2, konsumsi, dihost sendiri, ruang kerja
Catatan penggunaan
- Kebijakan ini hanya dapat digunakan sekali di bagian kebijakan.
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.
Contoh
Dalam contoh ini, semua parameter kueri dan jalur divalidasi dalam mode pencegahan dan header dalam mode deteksi. Validasi ditimpa untuk beberapa parameter header:
<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation">
<headers specified-parameter-action="detect" unspecified-parameter-action="detect">
<parameter name="Authorization" action="prevent" />
<parameter name="User-Agent" action="ignore" />
<parameter name="Host" action="ignore" />
<parameter name="Referrer" action="ignore" />
</headers>
</validate-parameters>
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
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 di Azure