Penanganan kesalahan dalam kebijakan API Management

BERLAKU UNTUK: Semua tingkatAN API Management

Dengan menyediakan objek ProxyError, Azure API Management memungkinkan penerbit untuk menanggapi kondisi kesalahan, yang mungkin terjadi selama pemrosesan permintaan. ProxyErrorObjek diakses melalui properti context.LastError dan dapat digunakan oleh kebijakan di on-error bagian kebijakan. Artikel ini menyediakan referensi untuk kemampuan penanganan kesalahan di Azure API Management.

Penanganan kesalahan di API Management

Kebijakan di Azure API Management dibagi menjadi inbound, backend, outbound, dan on-error bagian seperti yang ditunjukkan dalam contoh berikut.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

Selama pemrosesan permintaan, langkah-langkah bawaan dijalankan bersama dengan kebijakan mana pun, yang berada dalam ruang lingkup untuk permintaan tersebut. Jika terjadi kesalahan, pemrosesan segera melompat ke on-error bagian kebijakan. on-error Bagian kebijakan dapat digunakan pada lingkup mana pun. Penerbit API dapat mengonfigurasi perilaku kustom seperti mencatat kesalahan ke pusat aktivitas atau membuat respons baru untuk kembali ke penelepon.

Catatan

Bagian on-error ini tidak ada dalam kebijakan secara default. Untuk menambahkan bagian on-error ke kebijakan, telusuri kebijakan yang diinginkan di editor kebijakan dan tambah kebijakan. Untuk informasi selengkapnya tentang mengonfigurasi kebijakan, lihat Kebijakan dalam API Management.

Jika tidak ada bagian on-error, penelepon akan menerima 400 atau 500 pesan respons HTTP jika terjadi kondisi kesalahan.

Kebijakan yang diperbolehkan di dalam-kesalahan

Kebijakan berikut dapat digunakan di on-error bagian kebijakan.

• pilih
• atur-variabel
• temukan-dan-ganti
• respons-pengembalian
• atur-judul
• atur-metode
• atur-status
• kirim-permintaan
• kirim-permintaan-satu-arah
• log-to-eventhub
• json-ke-xml
• xml-ke-json
• konkurensi-batas
• respons-tiruan
• coba lagi
• jejak

Kesalahan Terakhir

Saat terjadi kesalahan dan kontrol melompat ke bagian kebijakan on-error, kesalahan disimpan di properti context.LastError, yang dapat diakses oleh kebijakan di bagian on-error. LastError memiliki properti berikut.

Nama	Tipe	Deskripsi	Wajib diisi
Source	benang	Nama-nama elemen di mana kesalahan terjadi. Bisa berupa kebijakan atau nama langkah alur bawaan.	Ya
Reason	benang	Kode kesalahan ramah mesin, yang dapat digunakan dalam penanganan kesalahan.	Tidak.
Message	benang	Deskripsi kesalahan yang dapat dibaca oleh manusia.	Ya
Scope	benang	Nama cakupan tempat kesalahan terjadi.	Tidak.
Section	benang	Nama bagian di mana terjadi kesalahan. Nilai yang mungkin: "masuk", "backend", "keluar", atau "di-kesalahan".	Tidak.
Path	benang	Menentukan hierarki kebijakan berlapis, misalnya "pilih[3]\saat[2]". Beberapa instans kebijakan berlapis diindeks dari 1.	Tidak.
PolicyId	benang	Nilai atribut id, jika ditentukan oleh pelanggan, pada kebijakan di mana terjadi kesalahan	Tidak.

Petunjuk / Saran

Anda dapat mengakses kode status melalui context.Response.StatusCode.

Catatan

Semua kebijakan memiliki atribut opsional idyang dapat ditambahkan ke elemen akar kebijakan. Jika atribut ini ada di dalam kebijakan ketika terjadi kondisi kesalahan, nilai atribut dapat diambil menggunakan properti context.LastError.PolicyId.

Kesalahan yang sudah ditentukan sebelumnya untuk langkah bawaan

Kesalahan berikut telah ditentukan sebelumnya untuk kondisi kesalahan yang dapat terjadi selama evaluasi langkah-langkah pemrosesan bawaan.

Sumber	Kondisi	Alasan	Pesan
konfigurasi	Uri tidak sesuai dengan API atau Operasi mana pun	OperationNotFound	Tidak bisa mencocokkan permintaan masuk dengan operasi.
otorisasi	Kunci langganan tidak disediakan	KunciLanggananTidakDitemukan	Akses ditolak karena kunci langganan tidak ada. Pastikan untuk menyertakan kunci langganan saat membuat permintaan ke API ini.
otorisasi	Nilai kunci langganan tidak valid	Kunci Langganan Tidak Valid	Akses ditolak karena kunci langganan tidak valid. Pastikan untuk menyediakan kunci yang valid untuk langganan yang aktif.
beberapa	Koneksi hilir (dari klien ke gateway API Management) dibatalkan oleh klien saat permintaan tertunda	ClientConnectionFailure	beberapa
beberapa	Koneksi hulu (dari gateway API Management ke layanan backend) tidak dibuat atau telah dibatalkan oleh backend	BackendConnectionFailure	beberapa
beberapa	Pengecualian runtime telah terjadi selama evaluasi ekspresi tertentu	ExpressionValueEvaluationFailure	beberapa

Kesalahan yang sudah ditentukan sebelumnya untuk kebijakan

Kesalahan berikut telah ditentukan sebelumnya untuk kondisi kesalahan yang dapat terjadi selama evaluasi kebijakan.

Sumber	Kondisi	Alasan	Pesan
batas-tarif	Melebihi batas tarif	Batas Penggunaan Terlampaui	Batas tarif telah dilampaui
kuota	Kuota terlampaui	Kuota Terlampaui	Kuota volume kehabisan panggilan. Kuota akan diisi ulang dalam xx:xx:xx. -atau- Kuota kehabisan bandwidth. Kuota akan diisi ulang dalam xx:xx:xx.
jsonp	Nilai parameter panggil balik tidak valid (berisi karakter yang salah)	CallbackParameterInvalid	Nilai parameter panggilan balik {callback-parameter-name} bukan pengidentifikasi JavaScript yang valid.
filter-ip	Gagal memilah IP penelepon dari permintaan	FailedToParseCallerIP	Gagal membuat alamat IP untuk penelepon. Akses ditolak.
filter-ip	IP penelepon tidak ada dalam daftar yang diperbolehkan	PemanggilIpTidakDiizinkan	Alamat IP penelepon {ip-address} tidak diperbolehkan. Akses ditolak.
filter-ip	IP penelepon dalam daftar yang diblokir	CallerIpBlocked	Alamat IP penelepon diblokir. Akses ditolak.
check-header	Judul yang diperlukan tidak disajikan atau tidak ada nilai	Header Tidak Ditemukan	Judul {header-name} tidak ditemukan dalam permintaan. Akses ditolak.
check-header	Judul yang diperlukan tidak disajikan atau tidak ada nilai	NilaiHeaderTidakDiizinkan	Nilai judul {header-name} dari {header-value} tidak diperbolehkan. Akses ditolak.
validasi-jwt	JWT tidak ada dalam permintaan	TokenNotPresent	JWT tidak ada.
validasi-jwt	Validasi tanda tangan gagal	Tanda Tangan Token Tidak Valid	<pesan dari pustaka jwt>. Akses ditolak.
validasi-jwt	Audiens tidak valid	TokenAudience Tidak Diizinkan	<pesan dari pustaka jwt>. Akses ditolak.
validasi-jwt	Penerbit tidak valid	Penerbit Token Tidak Diizinkan	<pesan dari pustaka jwt>. Akses ditolak.
validasi-jwt	Token telah kedaluwarsa	Token Kedaluwarsa	<pesan dari pustaka jwt>. Akses ditolak.
validasi-jwt	Kunci tanda tangan tidak diselesaikan dengan ID	KunciTandaTanganTokenTidakDitemukan	<pesan dari pustaka jwt>. Akses ditolak.
validasi-jwt	Klaim yang diperlukan tidak ada dari token	Token Klaim Tidak Ditemukan	JWT kehilangan klaim berikut: <c1>, <c2>, ... Akses ditolak.
validasi-jwt	Nilai klaim tidak cocok	NilaiKlaimTokenTidakDiizinkan	Nilai klaim {claim-name} dari {claim-value} tidak diperbolehkan. Akses ditolak.
validasi-jwt	Kegagalan validasi lain	JwtTidakValid	<pesan dari pustaka jwt>
permintaan-meneruskan atau kirim-permintaan	Kode status respons HTTP dan judul tidak diterima dari backend dalam batas waktu yang dikonfigurasi	Waktu habis	beberapa

Contoh

Mengatur kebijakan API untuk:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

dan mengirim permintaan yang tidak sah akan menghasilkan respons berikut:

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
• Repositori taman bermain kebijakan
• Toolkit kebijakan Azure API Management
• Mendapatkan bantuan Copilot untuk membuat, menjelaskan, dan memecahkan masalah kebijakan