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

LastError

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	string	Nama-nama elemen di mana kesalahan terjadi. Bisa berupa kebijakan atau nama langkah alur bawaan.	Ya
Reason	string	Kode kesalahan ramah mesin, yang dapat digunakan dalam penanganan kesalahan.	No
Message	string	Deskripsi kesalahan yang dapat dibaca oleh manusia.	Ya
Scope	string	Nama lingkup di mana kesalahan terjadi dan bisa menjadi salah satu "global", "produk", "api", atau "operasi"	No
Section	string	Nama bagian di mana terjadi kesalahan. Nilai yang mungkin: "masuk", "backend", "keluar", atau "di-kesalahan".	No
Path	string	Menentukan kebijakan bertumpuk, misalnya "pilih[3]/kapan[2]".	No
PolicyId	string	Nilai atribut id, jika ditentukan oleh pelanggan, pada kebijakan di mana terjadi kesalahan	No

Tip

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.
authorization	Kunci langganan tidak disediakan	SubscriptionKeyNotFound	Akses ditolak karena kunci langganan tidak ada. Pastikan untuk menyertakan kunci langganan saat membuat permintaan ke API ini.
authorization	Nilai kunci langganan tidak valid	SubscriptionKeyInvalid	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	RateLimitExceeded	Batas tarif telah dilampaui
kuota	Kuota terlampaui	QuotaExceeded	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	CallerIpNotAllowed	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	HeaderNotFound	Judul {header-name} tidak ditemukan dalam permintaan. Akses ditolak.
check-header	Judul yang diperlukan tidak disajikan atau tidak ada nilai	HeaderValueNotAllowed	Nilai judul {header-name} dari {header-value} tidak diperbolehkan. Akses ditolak.
validate-jwt	Token Jwt tidak ada dalam permintaan	TokenNotPresent	JWT tidak ada.
validate-jwt	Validasi tanda tangan gagal	TokenSignatureInvalid	<pesan dari pustaka jwt>. Akses ditolak.
validate-jwt	Audiens tidak valid	TokenAudienceNotAllowed	<pesan dari pustaka jwt>. Akses ditolak.
validate-jwt	Penerbit tidak valid	TokenIssuerNotAllowed	<pesan dari pustaka jwt>. Akses ditolak.
validate-jwt	Token telah kedaluwarsa	TokenExpired	<pesan dari pustaka jwt>. Akses ditolak.
validate-jwt	Kunci tanda tangan tidak diselesaikan dengan ID	TokenSignatureKeyNotFound	<pesan dari pustaka jwt>. Akses ditolak.
validate-jwt	Klaim yang diperlukan tidak ada dari token	TokenClaimNotFound	Token JWT tidak memiliki klaim berikut: <c1>, <c2>, … Akses ditolak.
validate-jwt	Nilai klaim tidak cocok	TokenClaimValueNotAllowed	Nilai klaim {claim-name} dari {claim-value} tidak diperbolehkan. Akses ditolak.
validate-jwt	Kegagalan validasi lain	JwtInvalid	<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:

Langkah berikutnya

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat:

• Kebijakan di API Management
• Transformasi API
• Referensi Kebijakan untuk daftar lengkap pernyataan kebijakan dan pengaturannya
• Sampel kebijakan