Bagikan melalui


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.

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:

Respons kesalahan tidak sah

Langkah berikutnya

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat: