Memvalidasi kode status
BERLAKU UNTUK: Semua tingkatAN API Management
Kebijakan validate-status-code memvalidasi kode status HTTP sebagai respons terhadap skema API. Kebijakan ini dapat digunakan untuk mencegah kebocoran kesalahan backend, yang dapat berisi jejak tumpukan.
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-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
<status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>
Atribut
| Atribut | Deskripsi | Wajib diisi | Default |
|---|---|---|---|
| unspecified-status-code-action | Tindakan yang harus dilakukan untuk kode status HTTP dalam tanggapan yang tidak ditentukan dalam skema API. 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 |
|---|---|---|
| status-code | Tambahkan satu atau beberapa elemen untuk kode status HTTP untuk mengambil alih tindakan validasi default untuk kode status sebagai respons. | No |
atribut kode status
| Atribut | Deskripsi | Wajib diisi | Default |
|---|---|---|---|
| kode | Kode status HTTP untuk mengganti tindakan validasi. | Ya | T/A |
| tindakan | Tindakan yang harus dilakukan untuk kode status yang cocok, yang tidak ditentukan dalam skema API. Jika kode status ditentukan dalam skema API, penggantian ini tidak berlaku. | Ya | 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: keluar, saat terjadi kesalahan
- 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
<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />
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