Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Banyak kondisi error dapat muncul saat proxy API melayani permintaan dari aplikasi. Misalnya, proxy API mungkin mengalami masalah jaringan saat berkomunikasi dengan layanan backend, aplikasi mungkin menampilkan kredensial yang sudah tidak berlaku, pesan permintaan mungkin diformat dengan tidak benar, dan sebagainya.
Jika terjadi error setelah aplikasi klien memanggil proxy API, pesan error akan ditampilkan ke klien. Secara default, klien menerima pesan error yang sering kali tidak jelas tanpa detail atau panduan. Namun, jika Anda ingin mengganti pesan error default dengan pesan kustom yang lebih berguna, dan bahkan memperkayanya dengan hal-hal seperti header HTTP tambahan, Anda perlu menyiapkan penanganan kesalahan kustom di Apigee.
Penanganan kesalahan kustom juga memungkinkan Anda menambahkan fungsi seperti logging pesan setiap kali terjadi error.
Sebelum membahas cara menerapkan penanganan error kustom di proxy API, sebaiknya Anda memahami cara terjadinya error dan reaksi proxy API terhadap error tersebut.
Video
Tonton video berikut untuk mempelajari lebih lanjut penanganan kesalahan.
Video | Deskripsi |
---|---|
Pengantar penanganan kesalahan dan alur error | Pelajari penanganan fault dan apa yang terjadi saat error terjadi di proxy API. |
Menangani kesalahan menggunakan aturan kesalahan | Pelajari cara menangani kesalahan menggunakan aturan kesalahan. |
Memunculkan kesalahan kustom menggunakan kebijakan RaiseFault | Menimbulkan kesalahan kustom selama runtime API menggunakan kebijakan RaiseFault. |
Menentukan aturan kesalahan di proxy API dan endpoint target | Tentukan aturan kesalahan di proxy API dan endpoint target, serta pahami perbedaannya. |
Memahami urutan eksekusi aturan kesalahan | Memahami urutan eksekusi aturan kesalahan di proxy API dan endpoint target. |
Menentukan aturan default | Tentukan aturan kesalahan default untuk menangani error umum di API Anda. |
Cara terjadinya error
Pertama, kita akan membahas bagaimana kesalahan terjadi. Mengetahui cara terjadinya error akan membantu Anda merencanakan berbagai situasi saat Anda ingin menerapkan penanganan error kustom.
Error otomatis
Proxy API otomatis menampilkan error dalam situasi berikut:
- Kebijakan menampilkan error. Misalnya, jika panggilan API mengirimkan kunci yang sudah habis masa berlakunya, kebijakan VerifyAPIKey akan otomatis memunculkan error; atau jika jumlah panggilan API melebihi batas tertentu, kebijakan Quota atau kebijakan SpikeArrest akan memunculkan error. (Lihat Referensi error kebijakan untuk mengetahui jenis error yang dapat ditimbulkan oleh kebijakan).
- Ada masalah dalam alur pesan proxy API, seperti error perutean.
- Terjadi kegagalan backend, seperti error HTTP karena kegagalan tingkat protokol, error TLS/SSL, atau layanan target tidak tersedia.
- Terjadi kegagalan tingkat sistem, seperti pengecualian kehabisan memori.
Untuk mengetahui informasi selengkapnya tentang error ini, lihat Taksonomi kesalahan dalam topik ini.
Error kustom
Untuk situasi yang tidak memiliki error otomatis, Anda mungkin ingin memunculkan error kustom; misalnya, jika respons berisi kata unavailable
, atau jika kode status HTTP lebih besar dari 201
. Lakukan ini dengan menambahkan kebijakan RaiseFault ke
tempat yang sesuai dalam alur proxy API.
Anda dapat menambahkan kebijakan RaiseFault ke alur proxy API seperti halnya kebijakan lainnya. Dalam
contoh konfigurasi proxy berikut, kebijakan Raise-Fault-1
dilampirkan ke
respons TargetEndpoint. Jika kata unavailable
ada dalam respons dari layanan target, kebijakan RaiseFault akan dieksekusi dan memunculkan error.
<TargetEndpoint name="default"> ... <Response> <Step> <Name>Raise-Fault-1</Name> <Condition>message.content Like "*unavailable*"</Condition> </Step> </Response>
Hal ini hanya untuk menunjukkan bahwa Anda dapat memunculkan error kustom. Kami membahas lebih mendetail kebijakan RaiseFault di bagian Kebijakan FaultRules vs. kebijakan RaiseFault.
Untuk contoh lainnya, lihat postingan Komunitas Apigee berikut:
Tindakan proxy API saat terjadi error
Berikut yang terjadi saat proxy memunculkan error.
Keluar dari pipeline proxy
Saat mengalami error, terlepas dari penyebabnya, proxy API akan keluar dari pipeline alur normal, memasuki status error, dan menampilkan pesan error ke aplikasi klien. Setelah memasuki status error, proxy API tidak dapat mengembalikan pemrosesan ke pipeline alur normal.
Misalnya, asumsikan proxy API memiliki kebijakan dalam urutan berikut dalam permintaan ProxyEndpoint:
- Verifikasi Kunci API
- Kuota
- JSON ke XML
Jika terjadi error selama verifikasi kunci API, proxy API akan berpindah ke status error. Kebijakan Kuota dan JSON ke XML tidak dijalankan, proxy tidak melanjutkan ke TargetEndpoint, dan pesan error ditampilkan ke aplikasi klien.
Memeriksa FaultRules
Dalam status error, proxy API juga memeriksa keberadaan hal berikut (secara berurutan) dalam konfigurasi proxy API sebelum menampilkan pesan error default ke aplikasi klien:
- Bagian
<FaultRules>
, yang berisi logika untuk memicu pesan error kustom (dan kebijakan lainnya) berdasarkan kondisi tertentu yang Anda tentukan. - Bagian
<DefaultFaultRule>
, yang memicu pesan error default dalam situasi berikut:- Tidak ada
<FaultRules>
yang ditentukan. - Tidak ada
<FaultRules>
yang ada yang dieksekusi. - Elemen
<AlwaysEnforce>
disetel ke benar (true).
- Tidak ada
Pada dasarnya, proxy API memberi Anda kesempatan untuk menampilkan pesan error kustom dan memicu logika lain. Jika proxy tidak menemukan kedua bagian tersebut, atau bagian tersebut ada tetapi tidak ada kesalahan kustom yang dipicu, proxy akan mengirim pesan default yang dibuat Apigee.
Contoh penanganan kesalahan sederhana
Mari kita mulai dengan contoh sederhana, saat panggilan ke proxy API tidak berisi kunci API yang diperlukan. Secara default, berikut adalah respons yang ditampilkan ke aplikasi klien:
HTTP/1.1 401 Unauthorized Date: Wed, 20 Jul 2016 19:19:32 GMT Content-Type: application/json Content-Length: 150 Connection: keep-alive Server: Apigee Router * Connection #0 to host myorg-test.apigee.net left intact {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Pengguna API Anda mungkin dapat memahami pesan error, tetapi mungkin juga tidak. Selain itu, banyak error default yang lebih halus dan sulit diuraikan.
Sebagai developer API, Anda dapat mengubah pesan ini untuk memenuhi kebutuhan siapa pun yang akan menerima pesan error, baik itu developer aplikasi iOS maupun grup pengujian internal yang memiliki persyaratan format pesan error sendiri.
Berikut contoh dasar cara membuat pesan error kustom untuk menangani error ini. Hal ini memerlukan 1) kebijakan yang menentukan pesan kustom, dan 2) FaultRule yang menjalankan kebijakan saat proxy mengalami error.
1. Buat kebijakan yang menentukan pesan kustom
Pertama, buat kebijakan yang menentukan pesan error kustom. Anda dapat menggunakan jenis kebijakan apa pun, seperti kebijakan AssignMessage, yang dapat menetapkan payload dan header HTTP opsional seperti kode status. Kebijakan AssignMessage sangat ideal untuk hal ini. Dengan begitu, Anda dapat mengontrol payload pesan, menetapkan kode status HTTP yang berbeda, dan menambahkan header HTTP.
Anda tidak perlu melampirkan kebijakan ke alur; cukup buat kebijakan tersebut, seperti yang dijelaskan dalam Membuat kebijakan.
Berikut adalah contoh kebijakan AssignMessage yang:
- Menampilkan pesan JSON.
- Menetapkan kode status HTTP (
911
, yang merupakan kode status yang jelas tidak ada hanya untuk mengilustrasikan fleksibilitas yang Anda miliki). Kode status muncul di header HTTP. - Membuat dan mengisi header HTTP baru bernama
invalidKey
.
<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message"> <DisplayName>Invalid key message</DisplayName> <Set> <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload> <StatusCode>911</StatusCode> </Set> <Add> <Headers> <Header name="invalidKey">Invalid API key!</Header> </Headers> </Add> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Saat kebijakan ini dijalankan, respons ke aplikasi klien akan terlihat seperti berikut. Bandingkan dengan respons default yang ditampilkan sebelumnya.
HTTP/1.1 911 Rejected by API Key Emergency Services Date: Wed, 20 Jul 2016 18:42:36 GMT Content-Type: application/json Content-Length: 35 Connection: keep-alive invalidKey: Invalid API key! Server: Apigee Router * Connection #0 to host myorg-test.apigee.net left intact {"Citizen":"Where's your API key? I don't see it as a query parameter."}
Ya, memang sedikit konyol, tetapi menunjukkan apa yang dapat dilakukan. Setidaknya sekarang developer yang menerima pesan tahu bahwa mereka lupa menyertakan kunci API sebagai parameter kueri.
Namun, bagaimana kebijakan ini dieksekusi? Bagian berikutnya akan menunjukkannya.
2. Buat <FaultRule> yang akan memicu kebijakan
Di bagian <ProxyEndpoint>
atau <TargetEndpoint>
konfigurasi proxy, Anda akan menambahkan blok XML <FaultRules>
yang berisi satu atau beberapa bagian <FaultRule>
. Setiap FaultRule merepresentasikan
error berbeda yang ingin Anda tangani. Dalam contoh sederhana ini, kita hanya akan menggunakan satu FaultRule untuk menunjukkan
komponennya.
Anda juga harus menambahkan <DefaultFaultRule>
untuk memberikan pesan error umum kustom jika tidak ada FaultRule yang dijalankan.
Contoh
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> </FaultRules> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Poin utama:
- FaultRules ditentukan di ProxyEndpoint. Ini penting. Selengkapnya tentang cara menempatkan FaultRules di ProxyEndpoint vs. TargetEndpoint nanti.
<Name>
: Nama kebijakan yang akan dijalankan. Nama berasal dari atributname
kebijakan pada elemen induk, seperti yang ditunjukkan dalam contoh kebijakan sebelumnya.-
<Condition>
: Apigee mengevaluasi kondisi dan menjalankan kebijakan hanya jika kondisinya benar. Jika ada beberapa FaultRule yang dievaluasi menjadi benar, Apigee akan menjalankan FaultRule pertama yang benar. (Penting: Urutan evaluasi FaultRule, dari atas ke bawah atau dari bawah ke atas, berbeda antara TargetEndpoint dan ProxyEndpoint, seperti yang dijelaskan di bagian Beberapa FaultRule dan logika eksekusi.) Jika Anda tidak menyertakan kondisi, FaultRule akan otomatis bernilai benar. Namun, hal itu bukan praktik terbaik. Setiap FaultRule harus memiliki kondisinya sendiri. -
<DefaultFaultRule>
: Jika tidak ada FaultRule kustom yang dieksekusi,<DefaultFaultRule>
akan dieksekusi, sehingga mengirim pesan kustom yang lebih umum, bukan pesan default yang tidak jelas yang dihasilkan Apigee.<DefaultFaultRule>
juga dapat memiliki<Condition>
, tetapi dalam sebagian besar kasus, Anda tidak akan menyertakannya, karena Anda ingin<Condition>
dieksekusi apa pun yang terjadi sebagai upaya terakhir.DefaultFaultRule biasanya digunakan untuk menampilkan pesan error umum untuk setiap error yang tidak terduga. Contohnya adalah pesan yang berisi informasi kontak untuk dukungan teknis. Respons default ini memiliki tujuan ganda, yaitu memberikan informasi yang mudah dipahami developer sekaligus meng-obfuscate URL backend atau informasi lain yang dapat digunakan untuk membahayakan sistem.
Beberapa FaultRule dan logika eksekusi
Di bagian Contoh penanganan kesalahan sederhana, kita menggunakan contoh sederhana
dari satu FaultRule dan kondisi. Dalam project API sebenarnya, dengan semua kemungkinan error yang dapat terjadi, Anda kemungkinan akan memiliki beberapa FaultRule dan DefaultFaultRule di <ProxyEndpoint>
dan <TargetEndpoint>
. Namun, pada akhirnya,
hanya satu FaultRule yang dijalankan saat proxy API memasuki status error.
Bagian ini menjelaskan logika yang digunakan Apigee dalam menangani FaultRule, mulai dari cara Apigee menentukan
FaultRule tunggal yang akan dieksekusi hingga cara menangani kondisi Langkah dalam saat FaultRule-nya
dipicu. Bagian ini juga memberikan panduan tentang kapan harus menentukan FaultRule di
<ProxyEndpoint>
vs. <TargetEndpoint>
, dan menjelaskan
hubungan antara FaultRule dan kebijakan RaiseFault.
Eksekusi FaultRules
Singkatnya, berikut logika yang digunakan Apigee saat proxy API mengalami error. Perhatikan bahwa ada sedikit perbedaan antara evaluasi FaultRules di ProxyEndpoint dan TargetEndpoint.
- Apigee mengevaluasi FaultRules di ProxyEndpoint atau TargetEndpoint, bergantung pada
tempat terjadinya error:
- ProxyEndpoint - Apigee dimulai dengan bawah
<FaultRule>
dalam XML konfigurasi dan berjalan ke atas, mengevaluasi<Condition>
setiap<FaultRule>
(kondisi luar, bukan kondisi<Step>
dalam). - TargetEndpoint - Apigee dimulai dengan top
<FaultRule>
dalam XML konfigurasi dan berlanjut ke bawah, mengevaluasi<Condition>
setiap<FaultRule>
(kondisi luar, bukan kondisi<Step>
dalam).
- ProxyEndpoint - Apigee dimulai dengan bawah
- Mengeksekusi FaultRule pertama yang kondisinya benar. Jika FaultRule tidak memiliki
kondisi, FaultRule akan bernilai benar secara default.
- Saat FaultRule dijalankan, semua Langkah di dalam FaultRule dievaluasi secara berurutan,
dari atas ke bawah dalam konfigurasi XML. Langkah-langkah tanpa kondisi akan dijalankan secara otomatis
(kebijakan dijalankan), dan Langkah-langkah yang memiliki
<Condition>
yang dievaluasi menjadi akan dijalankan (kondisi yang dievaluasi menjadicode
tidak dijalankan). -
Jika FaultRule dieksekusi, tetapi tidak ada langkah-langkah dalam FaultRule yang dieksekusi (karena kondisinya bernilai
code
), pesan error default yang dibuat Apigee akan ditampilkan ke aplikasi klien.<DefaultFaultRule>
tidak dieksekusi, karena Apigee telah mengeksekusi satu FaultRule-nya.
- Saat FaultRule dijalankan, semua Langkah di dalam FaultRule dievaluasi secara berurutan,
dari atas ke bawah dalam konfigurasi XML. Langkah-langkah tanpa kondisi akan dijalankan secara otomatis
(kebijakan dijalankan), dan Langkah-langkah yang memiliki
- Jika tidak ada FaultRule yang dieksekusi, Apigee akan mengeksekusi
<DefaultFaultRule>
, jika ada.
Berikut adalah contoh dengan komentar inline.
Eksekusi ProxyEndpoint
Evaluasi FaultRule ProxyEndpoint dilakukan dari bawah ke atas, jadi mulailah membaca dari FaultRule terakhir dalam contoh berikut dan lanjutkan ke atas. Lihat DefaultFaultRule terakhir.
<ProxyEndpoint name="default"> ... <FaultRules> <!-- 3. This FaultRule is automatically TRUE, because there's no outer condition. But because the FaultRule just below this got executed (bottom-to-top evaluation in a ProxyEndpoint), Apigee doesn't even evaluate this FaultRule. Note that it's not a best practice to have a FaultRule without an outer condition, which automatically makes the FaultRule true. --> <FaultRule name="random-error-message"> <Step> <Name>Random-fault</Name> </Step> </FaultRule> <!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation error. This is the first FaultRule to be TRUE, so it's executed. Now the Steps are evaluated, and for the ones whose conditions evaluate to TRUE, their policies are executed. Steps without conditions are automatically true. --> <FaultRule name="over_quota"> <Step> <Name>developer-over-quota-fault</Name> <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>global-over-quota-fault</Name> <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>log-error-message</Name> </Step> <Condition>(fault.name = "QuotaViolation")</Condition> </FaultRule> <!-- 1. Because this is the ProxyEndpoint, Apigee looks at this FaultRule first. But let's say this FaultRule is FALSE. A policy did not throw a FailedToResolveAPIKey error. Apigee moves UP to check the next FaultRule. --> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> </FaultRules> <!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. If a FaultRule is executed, but none of its Steps are executed, The DefaultFaultRule is not executed (because Apigee has already executed its one FaultRule). --> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Eksekusi TargetEndpoint
Evaluasi TargetEndpoint FaultRules dilakukan dari atas ke bawah, jadi mulailah membaca dari FaultRule pertama dalam contoh berikut dan lanjutkan ke bawah. Lihat DefaultFaultRule terakhir.
<TargetEndpoint name="default"> ... <FaultRules> <!-- 1. Because this is the TargetEndpoint, Apigee looks at this FaultRule first. Let's say this FaultRule is FALSE. A policy did not throw a FailedToResolveAPIKey error. Apigee moves down to the next FaultRule. --> <FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> </Step> <Condition>(fault.name = "FailedToResolveAPIKey")</Condition> </FaultRule> <!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation error. This is the first FaultRule to be TRUE, so it's executed. Now the Steps are evaluated, and for the ones whose conditions evaluate to TRUE, their policies are executed. Steps without conditions are automatically true. --> <FaultRule name="over_quota"> <Step> <Name>developer-over-quota-fault</Name> <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>global-over-quota-fault</Name> <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition> </Step> <Step> <Name>log-error-message</Name> </Step> <Condition>(fault.name = "QuotaViolation")</Condition> </FaultRule> <!-- 3. This FaultRule is automatically TRUE, because there's no outer condition. But because the FaultRule just above this got executed (top-to-bottom evaluation in a TargetEndpoint), Apigee doesn't even evaluate this FaultRule. Note that it's not a best practice to have a FaultRule without an outer condition, which automatically makes the FaultRule true. --> <FaultRule name="random-error-message"> <Step> <Name>Random-fault</Name> </Step> </FaultRule> </FaultRules> <!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. If a FaultRule is executed, but none of its Steps are executed, The DefaultFaultRule is not executed (because Apigee has already executed its one FaultRule). --> <DefaultFaultRule name="default-fault"> <Step> <Name>Default-message</Name> </Step> </DefaultFaultRule>
Urutan aturan kesalahan
Seperti yang dapat Anda lihat dalam contoh sebelumnya, urutan penempatan FaultRule Anda penting, bergantung pada apakah error terjadi di ProxyEndpoint atau TargetEndpoint.
Contoh:
Urutan ProxyEndpoint | Urutan TargetEndpoint |
---|---|
Dalam contoh berikut, karena evaluasi dilakukan dari bawah ke atas, FaultRule 3 dieksekusi, yang berarti FaultRule 2 dan 1 tidak dievaluasi. 5. FaultRule 1: FALSE 4. FaultRule 2: TRUE 3. FaultRule 3: TRUE 2. FaultRule 4: FALSE 1. FaultRule 5: FALSE |
Dalam contoh berikut, karena evaluasi dilakukan dari atas ke bawah, FaultRule 2 dieksekusi, yang berarti FaultRule 3, 4, dan 5 tidak dievaluasi. 1. FaultRule 1: FALSE 2. FaultRule 2: TRUE 3. FaultRule 3: TRUE 4. FaultRule 4: FALSE 5. FaultRule 5: FALSE |
Kebijakan yang akan disertakan
Anda dapat menjalankan kebijakan apa pun dari FaultRule dengan menempatkannya di Steps. Misalnya, Anda dapat mengeksekusi kebijakan AssignMessage untuk memformat respons ke aplikasi klien, lalu mencatat pesan dengan kebijakan MessageLogging. Kebijakan dijalankan dalam urutan yang Anda tetapkan (dari atas ke bawah dalam XML).
Aturan kesalahan dipicu HANYA dalam status error (tentang continueOnError)
Judul ini mungkin tampak seperti pengulangan, tetapi ada satu nuansa khusus yang perlu
diperhatikan terkait error proxy yang menyebabkan proxy API memasuki status error—atau
lebih tepatnya, tidak memasuki status error: atribut continueOnError
pada
kebijakan.
Singkatnya: Proxy API mengevaluasi <FaultRules>
dan
<DefaultFaultRule>
hanya jika proxy telah memasuki status error. Artinya, meskipun kondisi FaultRule dievaluasi ke benar, kondisi tersebut tidak akan dipicu jika proxy tidak dalam status error.
Namun, berikut contoh error yang terjadi dan proxy tidak memasuki status error. Pada
kebijakan apa pun, Anda dapat menetapkan atribut pada elemen induk yang disebut continueOnError
.
Atribut ini sangat penting terkait penanganan kesalahan, karena menentukan apakah
proxy memasuki status error jika kebijakan gagal atau tidak. Dalam sebagian besar kasus, sebaiknya Anda mempertahankan
continueOnError="false"
default, yang akan membuat proxy dalam status error jika
kebijakan gagal, dan penanganan error kustom Anda akan dipicu. Namun, jika
continueOnError="true"
(misalnya, jika Anda tidak ingin kegagalan Panggilan
Layanan menghentikan eksekusi proxy), proxy tidak akan masuk ke status error jika kebijakan
tersebut gagal, dan proxy tidak akan melihat FaultRules Anda.
Untuk mengetahui informasi tentang mencatat error saat continueOnError="true"
, lihat Menangani kesalahan kebijakan dalam alur saat ini.
Tempat untuk menentukan FaultRules: ProxyEndpoint atau TargetEndpoint
Saat proxy API mengalami error, error terjadi di
<ProxyEndpoint>
(permintaan dari atau respons ke aplikasi klien) atau di
<TargetEndpoint>
(permintaan ke atau respons dari layanan target). Di mana pun error
tersebut terjadi, di situlah Apigee mencari FaultRules.
Misalnya, jika server target tidak tersedia (kode status HTTP 503
), proxy API akan
berada dalam status error dalam respons <TargetEndpoint>
, dan alur proxy API normal
tidak akan berlanjut ke <ProxyEndpoint>
. Jika Anda hanya menentukan FaultRules di <ProxyEndpoint>
, FaultRules tersebut tidak akan menangani error tersebut.
Berikut contoh lainnya. Jika kebijakan RaiseFault pada respons <ProxyEndpoint>
memicu error, FaultRule di <TargetEndpoint>
tidak akan
dieksekusi.
FaultRules vs. kebijakan RaiseFault
Aturan kesalahan dan kebijakan RaiseFault mungkin pada awalnya terdengar seperti cara alternatif untuk menyelesaikan penanganan kesalahan; dan dalam beberapa hal, hal itu benar. Namun, keduanya juga bekerja sama. Bagian ini menjelaskan hubungan antara keduanya. Memahami hubungan ini akan membantu Anda mendesain penanganan kesalahan, terutama jika Anda ingin menggunakan keduanya.
Singkatnya:
- Aturan fault selalu dievaluasi saat proxy API memasuki status error.
-
Kebijakan RaiseFault adalah cara untuk menempatkan proxy API dalam status error ketika error tidak akan terjadi.
Misalnya, jika Anda ingin menampilkan error jika kode status HTTP dalam respons dari layanan target lebih besar dari
200
, Anda menambahkan kebijakan RaiseFault dalam alur respons. Tampilannya akan terlihat seperti ini:<TargetEndpoint name="default"> <PreFlow name="PreFlow"> ... <Response> <Step> <Name>Raise-Fault-1</Name> <!-- If the condition is true, the Raise-Fault-1 policy gets executed --> <Condition>(response.status.code GreaterThan "200")</Condition> </Step> </Response>
Kebijakan RaiseFault juga mengirimkan pesan error ke aplikasi klien.
Apa yang terjadi saat kebijakan RaiseFault memicu error, yang membuat proxy dalam status error, yang berpotensi menjalankan FaultRule? Di sinilah semuanya bisa menjadi sedikit rumit. Jika kebijakan RaiseFault menampilkan pesan error dan FaultRule dipicu dan menampilkan pesan error, apa yang akan ditampilkan ke aplikasi klien?
- Karena FaultRule atau DefaultFaultRule dijalankan setelah kebijakan RaiseFault, data respons FaultRule akan diprioritaskan.
- Data respons kebijakan RaiseFault (kode status atau payload pesan) akan digunakan jika data tersebut tidak ditetapkan oleh FaultRule atau DefaultFaultRule.
- Jika kebijakan RaiseFault dan FaultRule menambahkan header HTTP kustom, keduanya akan disertakan dalam respons. Nama header duplikat membuat header dengan beberapa nilai.
Berikut adalah contoh yang ditetapkan oleh kebijakan RaiseFault dan FaultRule, serta yang dikembalikan ke aplikasi klien. Contoh ini dirancang agar singkat, bukan untuk praktik terbaik.
Aplikasi klien menerima: Status Code: 468 Payload: {"Whoa":"Sorry."} Header: errorNote: woops,gremlins |
<- Kebijakan aturan kesalahan menetapkan ini: Status Code: [none] Payload: {"Whoa":"Sorry."} Header: errorNote: gremlins |
<- Kebijakan RaiseFault menetapkan ini: Status Code: 468 Payload: {"DOH!":"Try again."} Header: errorNote: woops |
Mem-build kondisi
Kondisi adalah kunci untuk eksekusi FaultRule. Anda membuat kondisi FaultRule dengan cara yang sama seperti yang Anda lakukan untuk kondisi lain di Apigee, seperti untuk kondisi alur bersyarat atau RaiseFault.
Untuk menempatkan bagian ini dalam konteks, berikut contoh aturan kesalahan yang memiliki kondisi FaultRule luar dan kondisi Step dalam.
<FaultRule name="invalid_key_rule"> <Step> <Name>invalid-key-message</Name> <Condition>oauthV2.Verify-API-Key-1.failed = true</Condition> </Step> <Condition>fault.name = "FailedToResolveAPIKey"</Condition> </FaultRule>
Variabel khusus untuk error kebijakan
Variabel fault.name
dan {policy_namespace}.{policy_name}.failed
tersedia saat kebijakan memunculkan error.
fault.name
Jika kebijakan gagal, tangkap error dalam kondisi menggunakan variabel fault.name
. Contoh:
<Condition>fault.name = "policy_error_name"</Condition>
Nama error muncul di pesan error default. Misalnya, pada contoh berikut, nama
kesalahannya adalah FailedToResolveAPIKey
. Dalam hal ini, variabel alur yang disebut
fault.name
ditetapkan ke nilai FailedToResolveAPIKey
.
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
Jadi, kondisinya akan terlihat seperti ini:
<Condition>fault.name = "FailedToResolveAPIKey"</Condition>
Lihat Referensi kesalahan kebijakan untuk mengetahui daftar kesalahan kebijakan.
{policy_namespace}.{policy_name}.failed
Variabel *.failed
tersedia saat kebijakan gagal. Berikut adalah
contoh variabel *.failed
untuk berbagai kebijakan.
Untuk namespace kebijakan, lihat variabel alur di setiap topik referensi kebijakan.
- Kebijakan RaiseFault:
raisefault.failed
(sama untuk semua kebijakan RaiseFault) - VerifyAPIKey policy:
oauthV2.{policy_name}.failed
, misalnya,oauthV2.Verify-API-Key-1.failed
- Kebijakan kuota dan kebijakan SpikeArrest:
ratelimit.{policy_name}.failed
, misalnya,ratelimit.Quota-1.failed
Variabel lain yang tersedia
Saat proxy API mengalami status error, satu-satunya variabel yang tersedia untuk digunakan dalam kondisi adalah:
- Variabel kebijakan yang gagal.
- Variabel pesan HTTP yang ada pada saat kegagalan. Misalnya, jika error
terjadi dalam respons, FaultRule di
<TargetEndpoint>
dapat menggunakan data HTTPresponse.status.code
,message.content
,error.content
, dan sebagainya. Atau jika kebijakan Kuota gagal, Anda dapat menggunakan variabelratelimit.{quota_policy_name}.exceed.count
. Gunakan Alat debug dan Referensi kebijakan untuk membantu Anda mengetahui variabel dan data HTTP mana yang tersedia.
Informasi selengkapnya
-
Kondisi: Referensi kondisi dan Variabel dan kondisi alur
- Error: Referensi error kebijakan
- Variabel: Referensi variabel alur, dan lihat halaman Referensi kebijakan untuk variabel yang tersedia dengan setiap kebijakan.
Praktik terbaik untuk penanganan kesalahan
Penanganan error adalah tugas desain arsitektur utama untuk pengembangan proxy API. Penting untuk meluangkan waktu untuk mencari tahu cara dan waktu Anda akan menangani error, menentukan isi pesan error, dan mendesain format pesan error. Setelah (atau saat) Anda mengetahuinya, gunakan praktik terbaik ini untuk membantu Anda dalam penerapan penanganan kesalahan.
Berikut adalah beberapa praktik terbaik dalam mendesain dan membangun penanganan kesalahan:
- Di FaultRules, Anda dapat menentukan jenis kebijakan apa pun. Pola yang paling umum adalah menggunakan kebijakan AssignMessage untuk menetapkan item tertentu dalam respons error yang tertunda. Anda juga dapat menggunakan AssignMessage untuk menetapkan variabel yang digunakan untuk tujuan lain, misalnya, untuk variabel yang dirujuk oleh kebijakan logging yang dijalankan di PostClientFlow, atau di FlowHooks. Pertimbangkan juga untuk mencatat pesan, misalnya dengan kebijakan MessageLogging atau kebijakan ServiceCallout, jika Anda ingin mencatat error tertentu dalam kondisi kesalahan tertentu.
- Jangan tentukan kebijakan RaiseFault sebagai Langkah dalam FaultRule. Lebih baik menggunakan kebijakan AssignMessage untuk menetapkan atau mengubah elemen pesan, termasuk payload, header, atau kode status.
- Untuk setiap FaultRule, atau untuk semua FaultRule kecuali yang terakhir dievaluasi,
berikan
<Condition>
luar yang dilampirkan sebagai turunan elemen<FaultRule>
. Kondisi eksekusi untuk FaultRule tanpa Kondisi eksplisit yang ditentukan, akan dievaluasi secara implisit menjaditrue
. Elemen<Condition>
yang dilampirkan sebagai turunan elemen<Step>
tidak digunakan untuk menentukan apakah kondisi eksekusi untuk FaultRule bernilaitrue
ataufalse
. Kondisi langkah dievaluasi hanya setelah Apigee mengeksekusi FaultRule yang memuatnya. Dalam FaultRule, biasanya ada beberapa Langkah dengan kebijakan AssignMessage (atau lainnya), masing-masing dengan kondisi Langkah. -
Untuk menangani error di beberapa kebijakan dengan jenis yang sama (misalnya, beberapa kebijakan Kuota), buat satu FaultRule per error kebijakan yang mungkin Anda terima, lalu bedakan antara error terpisah dengan Kondisi yang dilampirkan ke Langkah. Misalnya, buat FaultRule untuk menangani error dalam kebijakan Kuota, seperti
QuotaViolation
, dan FaultRule terpisah untukInvalidApiKey
. (Lihat Referensi error kebijakan untuk error kebijakan. Saat menemukan error tambahan yang perlu ditangani, Anda dapat kembali nanti dan menambahkannya ke FaultRules. Anda boleh melakukan iterasi, meskipun memerlukan deployment ulang proxy.) Dengan pendekatan ini, Anda dapat menemukan jenis error yang sama, terlepas dari kebijakan mana yang memunculkannya, sehingga membuat XML FaultRules Anda efisien.Kondisi Langkah dalam memberi Anda kontrol yang lebih terperinci. Misalnya, jika Anda menerapkan kuota developer individual dan kuota global dengan dua kebijakan dalam alur permintaan, tetapkan kondisi FaultRule luar agar dipicu pada error
QuotaViolation
(yang ditampilkan saat kuota terlampaui dalam kedua kasus). Kemudian tetapkan kondisi Langkah untuk mengevaluasi variabelexceed.count
tertentu dalam kedua kebijakan kuota Anda. Hanya error yang relevan yang dikirim ke klien (penggunaan berlebih kuota developer atau penggunaan berlebih kuota global). Berikut contoh konfigurasi ini:<FaultRule name="over_quota"> <!-- This condition catches a QuotaViolation in *any* Quota policy --> <Condition>fault.name = "QuotaViolation"</Condition> <Step> <Name>AM-developer-over-quota-fault</Name> <Condition>ratelimit.developer-quota-policy.exceed.count GreaterThan 0</Condition> </Step> <Step> <Name>AM-global-over-quota-fault</Name> <Condition>ratelimit.global-quota-policy.exceed.count GreaterThan 0</Condition> </Step> </FaultRule>
Untuk contoh lain, lihat diskusi ini tentang Penanganan kesalahan kebijakan.
-
Untuk menangani error saat Anda menggunakan satu kebijakan dari satu jenis, pertimbangkan aturan kesalahan tunggal yang dijalankan saat satu kebijakan tersebut gagal, dan sertakan beberapa langkah yang dipetakan ke setiap kemungkinan error. Hal ini membuat XML Anda lebih sederhana dengan menggunakan satu FaultRule, bukan beberapa FaultRule (satu untuk setiap jenis error). Misalnya, Anda dapat menentukan bahwa langkah-langkah kebijakan AssignMessage yang berbeda dijalankan dalam kondisi yang berbeda, seperti ini:
<FaultRule name="raise-fault-3"> <!-- This condition catches *any* error in the Verify-API-Key-1 policy. --> <Condition>oauthV2.Verify-API-Key-1.failed = "true"</Condition> <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. --> <Step> <Name>AM-Generic-Key-Fault</Name> </Step> <Step> <Name>AM-API-Key-NotFound</Name> <Condition>fault.name = "FailedToResolveAPIKey"</Condition> </Step> <Step> <Name>AM-API-Key-Invalid</Name> <Condition>fault.name = "InvalidApiKey"</Condition> </Step> </FaultRule>
- Tambahkan FaultRules tempat terjadinya error (sisi klien
<ProxyEndpoint>
atau sisi target<TargetEndpoint>
). Sertakan FaultRules untuk setiap kebijakan yang muncul di setiap lokasi. - Saat menggunakan kebijakan RaiseFault bersama dengan FaultRules, koordinasikan data respons yang dikirim kembali saat kebijakan RaiseFault dan FaultRule menampilkan data. Misalnya, jika Anda memiliki kebijakan RaiseFault yang menetapkan kode status HTTP, jangan juga mengonfigurasi Langkah AssignMessage dalam FaultRule yang mereset kode status. Hal terburuk yang dapat terjadi adalah kode status default ditampilkan ke aplikasi klien.
-
Elemen
<DefaultFaultRule>
melengkapi elemen<FaultRules>
untuk memberi Anda kontrol lebih besar atas kebijakan yang dijalankan proxy saat menangani status kesalahan. Jika Anda menentukan<DefaultFaultRule>
,<DefaultFaultRule>
akan dieksekusi jika salah satu atau kedua hal berikut terpenuhi:- Tidak ada FaultRule lain yang telah dieksekusi. Kasus khusus di sini adalah jika tidak ada elemen
<FaultRules>
yang dikonfigurasi sama sekali. - Jika elemen turunan
<AlwaysEnforce>
dari<DefaultFaultRule>
bernilai benar (true).
Anda juga dapat menentukan elemen
<Condition>
pada<DefaultFaultRule>
. Anda mungkin ingin melakukannya untuk mengecualikan eksekusinya berdasarkan beberapa status permintaan atau pesan error yang tertunda, misalnya jika header tertentu ada atau tidak ada.Gunakan
<DefaultFaultRule>
dengan<AlwaysEnforce>
yang disetel ketrue
, jika Anda memiliki satu atau beberapa kebijakan yang ingin Anda jalankan oleh proxy secara terus-menerus, terlepas dari apakah FaultRule sebelumnya telah dieksekusi atau tidak. Salah satu kemungkinan skenario: misalkan Anda ingin menyuntikkan header ke dalam respons dalam semua kasus, baik permintaan proxy menghasilkan kesalahan atau tidak, dan apakah kesalahan telah ditangani sebelumnya atau tidak. Kemudian, Anda akan melampirkan kebijakan AssignMessage yang sesuai di bagian<PostFlow>
/<Response>
, dan juga melampirkan kebijakan yang sama di<DefaultFaultRule>
dengan<AlwaysEnforce>
ditetapkan ketrue
. - Tidak ada FaultRule lain yang telah dieksekusi. Kasus khusus di sini adalah jika tidak ada elemen
Pola untuk penanganan kesalahan yang terpusat dan dapat digunakan kembali
Pola penanganan error untuk proxy Apigee menjelaskan pola untuk penanganan kesalahan terpusat tanpa duplikasi kode.
Membuat FaultRules
Untuk menambahkan FaultRule, Anda perlu mengedit konfigurasi XML ProxyEndpoint atau TargetEndpoint. Anda dapat menggunakan UI Apigee untuk melakukan pengeditan ini di panel Code pada tampilan Develop untuk proxy API, atau mengedit file XML yang menentukan ProxyEndpoint atau TargetEndpoint.
Jika Anda membuat FaultRule di UI Apigee, buat kebijakan yang ingin Anda jalankan terlebih dahulu, lalu tambahkan ke konfigurasi FaultRule. (Anda akan mendapatkan error di UI jika mencoba menyimpan FaultRule yang mereferensikan kebijakan yang belum dibuat.)
Menambahkan kebijakan ke FaultRule
Meskipun Anda dapat menempatkan kebijakan apa pun di FaultRule, Anda biasanya menggunakan kebijakan AssignMessage untuk membuat pesan respons kustom untuk kondisi error. AssignMessage memungkinkan Anda mengonfigurasi respons HTTP dengan payload, kode status HTTP, dan header.
Contoh di bawah menunjukkan konfigurasi AssignMessage policy standar:
<AssignMessage name="AM-Invalid-Key"> <Set> <Payload contentType="text/plain">That is an error.</Payload> <StatusCode>401</StatusCode> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Perhatikan bahwa elemen <AssignTo>
tidak ditentukan. Artinya, pesan tersebut akan ditetapkan ke pesan sekitar, bergantung pada tempat kebijakan dilampirkan.
Sekarang Anda dapat menggunakan kebijakan ini di FaultRule. Perhatikan cara Anda mereferensikan kebijakan AssignMessage berdasarkan nama di FaultRule:
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>AM-Invalid-Key</Name> </Step> <Condition>fault.name = "InvalidApiKey"</Condition> </FaultRule> </FaultRules> </ProxyEndpoint>
Saat Anda men-deploy konfigurasi di atas, proxy API akan menjalankan kebijakan AssignMessage
yang disebut AM-Invalid-Key
setiap kali aplikasi memberikan kunci API yang tidak valid.
Anda dapat menjalankan beberapa kebijakan dalam FaultRule, seperti yang ditunjukkan contoh berikut:
<ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="invalid_key_rule"> <Step> <Name>AM-Invalid-Key</Name> </Step> <Step> <Name>policy2</Name> </Step> <Step> <Name>policy3</Name> </Step> <Condition>fault.name = "InvalidApiKey"</Condition> </FaultRule> </FaultRules> </ProxyEndpoint>
Kebijakan dijalankan dalam urutan yang ditentukan. Misalnya, Anda dapat menggunakan kebijakan MessageLogging, kebijakan ExtractVariables, kebijakan AssignMessage, atau kebijakan lain dalam FaultRule. Perhatikan bahwa pemrosesan FaultRule akan segera berhenti jika salah satu situasi berikut terjadi:
- Kebijakan apa pun di FaultRule menyebabkan error
- Salah satu kebijakan di FaultRule berjenis RaiseFault
Menentukan pesan error kustom yang ditampilkan dari FaultRule
Sebagai praktik terbaik, Anda harus menentukan respons error yang jelas dari API Anda. Dengan begitu, Anda dapat memberikan informasi yang konsisten dan bermanfaat kepada klien.
Contoh kebijakan AssignMessage berikut menggunakan tag <Payload>
dan
<StatusCode>
untuk menentukan respons
error kustom yang dikirim kembali ke klien saat terjadi error InvalidApiKey (lihat contoh FaultRules
sebelumnya).
<AssignMessage name="AM-Invalid-Key"> <Set> <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. Contact support at support@mycompany.com.</Payload> <StatusCode>401</StatusCode> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Respons ini menyertakan:
- Payload yang berisi pesan error dan alamat email untuk menghubungi dukungan.
- Kode status HTTP yang ditampilkan dalam respons.
Membuat DefaultFaultRule
DefaultFaultRule bertindak sebagai pengendali pengecualian untuk error apa pun yang tidak ditangani secara eksplisit oleh
FaultRule lain. Jika kondisi untuk semua FaultRule tidak cocok dengan error, maka
DefaultFaultRule akan menangani error. Aktifkan penanganan kesalahan default dengan menambahkan
tag <DefaultFaultRule>
sebagai elemen turunan ProxyEndpoint atau
TargetEndpoint.
Misalnya, konfigurasi TargetEndpoint di bawah menentukan DefaultFaultRule yang memanggil
kebijakan bernama AM-Return-Generic-Error
:
<TargetEndpoint name="default"> ... <FaultRules> ... </FaultRules> <DefaultFaultRule name="fault-rule"> <Step> <Name>AM-Return-Generic-Error</Name> </Step> </DefaultFaultRule> <HTTPTargetConnection> <URL>https://mytarget.example.net</URL> </HTTPTargetConnection> </TargetEndpoint>
DefaultFaultRule biasanya digunakan untuk menampilkan pesan error umum untuk error yang tidak terduga, seperti pesan yang berisi informasi kontak untuk dukungan teknis. Respons default ini memiliki tujuan ganda, yaitu memberikan informasi yang mudah digunakan oleh developer sekaligus mengaburkan URL backend atau informasi lain yang dapat digunakan untuk membahayakan sistem.
Misalnya, Anda menentukan kebijakan AssignMessage berikut untuk menampilkan error umum:
<AssignMessage name="AM-Return-Generic-Error"> <Set> <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload> </Set> </AssignMessage>
Sertakan elemen <AlwaysEnforce>
dalam
tag <DefaultFaultRule>
untuk menjalankan DefaultFaultRule untuk setiap error, meskipun
FaultRule lain telah dijalankan. DefaultFaultRule selalu menjadi FaultRule terakhir
yang dieksekusi:
<DefaultFaultRule name="fault-rule"> <Step> <Name>AM-Return-Generic-Error</Name> </Step> <AlwaysEnforce>true</AlwaysEnforce> </DefaultFaultRule>
Salah satu penggunaan DefaultFaultRule adalah untuk menentukan jenis error yang terjadi saat Anda
tidak dapat menentukannya. Misalnya, jika proxy API Anda gagal karena error yang tidak dapat Anda
tentukan, Anda dapat menggunakan DefaultFaultRule untuk memanggil kebijakan AssignMessage berikut. Kebijakan ini menulis nilai fault.name
ke header bernama Unhandled-Fault
dalam respons:
<AssignMessage name="AM-Set-Fault-Header"> <Set> <Headers> <Header name="Unhandled-Fault">{fault.name}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
Kemudian, Anda dapat melihat header di alat Debug atau pada respons untuk melihat penyebab error.
Menambahkan logging pesan ke PostClientFlow
PostClientFlow adalah satu-satunya alur yang dieksekusi setelah proxy memasuki status error. Hanya kebijakan MessageLogging yang dapat dilampirkan ke alur ini, yang dijalankan setelah respons dikirim kembali ke klien. Meskipun melampirkan kebijakan MessageLogging ke alur ini secara teknis bukan penanganan error, Anda dapat menggunakannya untuk mencatat informasi jika terjadi error. Karena dijalankan terlepas dari apakah proxy berhasil atau gagal, Anda dapat menempatkan kebijakan Pencatatan Pesan di PostClientFlow dan dijamin akan selalu dijalankan.
Menangani kesalahan kebijakan dalam alur saat ini
Contoh yang ditampilkan sejauh ini semuanya menggunakan FaultRule di ProxyEndpoint atau TargetEndpoint untuk menangani
semua error kebijakan sebagai bagian dari status error. Hal ini karena nilai default elemen
continueOnError
dari kebijakan adalah false
, yang berarti bahwa saat
terjadi error dalam kebijakan, kontrol akan diarahkan ke status error. Setelah dalam status error, Anda
tidak dapat mengembalikan kontrol ke pipeline normal dan biasanya Anda akan menampilkan beberapa bentuk pesan
error ke aplikasi yang memanggil.
Namun, jika Anda menyetel elemen continueOnError
ke true
untuk
kebijakan, kontrol akan tetap berada dalam alur saat ini dan kebijakan berikutnya dalam pipeline akan dieksekusi setelah
kebijakan yang menyebabkan error. Keuntungan menangani error dalam alur saat ini adalah Anda
mungkin memiliki cara untuk memulihkan dari error untuk menyelesaikan pemrosesan permintaan.
Di bawah ini ditampilkan VerifyAPIKey policy bernama verify-api-key
dengan
elemen continueOnError
yang ditetapkan ke true:
<VerifyAPIKey continueOnError="true" name="verify-api-key"> <DisplayName>Verify API Key</DisplayName> <APIKey ref="request.queryparam.apikey"/> </VerifyAPIKey>
Jika kunci API tidak ada atau tidak valid, kebijakan VerifyAPIKey akan menetapkan
variabel oauthV2.verify-api-key.failed
ke true
, tetapi pemrosesan
berlanjut dalam alur saat ini.
Kemudian, Anda menambahkan kebijakan VerifyAPIKey sebagai langkah dalam PreFlow ProxyEndpoint:
<ProxyEndpoint name="default"> ... <PreFlow name="PreFlow"> <Request> <Step> <Name>verify-api-key</Name> </Step> <Step> <Name>FaultInFlow</Name> <Condition>oauthV2.verify-api-key.failed = "true"</Condition> </Step> </Request> <Response/> </PreFlow> </ProxyEndpoint>
Perhatikan bagaimana langkah berikutnya di PreFlow menggunakan kondisi untuk menguji keberadaan
error. Jika terjadi error dalam kebijakan VerifyAPIKey, kebijakan bernama
FaultInFlow
akan dieksekusi. Jika tidak, kebijakan FaultInFlow
akan dilewati. Kebijakan FaultInFlow
dapat melakukan banyak hal, seperti mencatat error,
mencoba memperbaiki error, atau melakukan tindakan lainnya.
Memicu error menggunakan kebijakan RaiseFault
Anda dapat menggunakan kebijakan RaiseFault kapan saja dalam alur untuk memicu error. Saat kebijakan RaiseFault dieksekusi, kebijakan tersebut akan menghentikan alur saat ini dan mentransfer kontrol ke status error.
Salah satu penggunaan kebijakan RaiseFault adalah untuk menguji kondisi tertentu yang mungkin tidak terdeteksi oleh kebijakan lain. Pada contoh di atas, Anda menambahkan tag <Condition>
ke tag
PreFlow <Step>
yang menyebabkan kebijakan FaultInFlow
dijalankan
jika kondisi terpenuhi. Jika FaultInFlow
adalah kebijakan RaiseFault, kontrol
akan ditransfer ke status error. Atau, Anda dapat menyisipkan kebijakan RaiseFault dalam alur untuk men-debug dan
menguji FaultRules Anda.
Saat kebijakan RaiseFault memicu error, Anda dapat menggunakan FaultRule dan kondisi berikut untuk memprosesnya:
<FaultRule name="raisefault_rule"> <Step> <Name>POLICY-NAME-HERE</Name> </Step> <Condition>fault.name = "RaiseFault"</Condition> </FaultRule>
Perhatikan bahwa kondisi tersebut menguji kesalahan bernama RaiseFault
. Kebijakan RaiseFault
selalu menetapkan nilai fault.name
ke RaiseFault
. Anda juga dapat
menetapkan variabel kustom dalam kebijakan RaiseFault. Jika melakukannya, Anda dapat menguji variabel tersebut
dalam elemen Kondisi.
Penanganan kode error HTTP kustom dari server target
Contoh yang ditampilkan di bagian sebelumnya berlaku untuk error yang dibuat oleh kebijakan. Namun, Anda juga dapat membuat respons kustom untuk error tingkat transportasi, yang berarti error HTTP yang ditampilkan dari server target. Untuk mengontrol respons dari error HTTP, konfigurasi TargetEndpoint untuk memproses kode respons HTTP.
Secara default, Apigee memperlakukan kode respons HTTP dalam rentang 1xx-3xx
sebagai
berhasil, dan kode respons HTTP dalam rentang 4xx-5xx
sebagai gagal. Artinya, setiap respons dari layanan backend dengan kode respons HTTP 4xx-5xx
akan otomatis memanggil status error, yang kemudian menampilkan pesan error langsung ke klien yang meminta.
Anda dapat membuat pengendali kustom untuk kode respons HTTP apa pun. Misalnya, Anda mungkin tidak ingin
memperlakukan semua kode respons HTTP dalam rentang 4xx-5xx
sebagai "kegagalan", tetapi hanya
5xx
, atau Anda mungkin ingin
menampilkan pesan error kustom untuk kode respons HTTP 400
dan 500
.
Dalam contoh berikutnya, Anda menggunakan properti success.codes
untuk mengonfigurasi
TargetEndpoint agar memperlakukan kode respons HTTP 400
dan 500
sebagai keberhasilan,
bersama dengan kode HTTP
default. Dengan memperlakukan kode tersebut sebagai keberhasilan, TargetEndpoint mengambil alih pemrosesan
pesan respons, bukan memanggil status error:
<TargetEndpoint name="default"> ... <HTTPTargetConnection> <Properties> <Property name="success.codes">1xx,2xx,3xx,400,500</Property> </Properties> <URL>http://weather.yahooapis.com</URL> </HTTPTargetConnection> </TargetEndpoint>
Seperti yang dapat Anda lihat dalam contoh ini, Anda dapat menggunakan karakter pengganti untuk menetapkan properti success.codes ke rentang nilai.
Menetapkan properti success.codes
akan menggantikan
nilai default. Oleh karena itu, jika Anda ingin menambahkan kode HTTP 400
ke daftar kode keberhasilan default, tetapkan properti ini sebagai:
<Property name="success.codes">1xx,2xx,3xx,400</Property>
Namun, jika Anda hanya ingin kode HTTP 400
dianggap sebagai kode keberhasilan, tetapkan properti sebagai:
<Property name="success.codes">400</Property>
Sekarang Anda dapat menentukan handler kustom untuk kode respons HTTP 400
dan 500
untuk menampilkan pesan respons
yang disesuaikan ke aplikasi yang meminta. TargetEndpoint berikut menggunakan kebijakan bernama
ReturnError
untuk menangani kode respons HTTP 400
dan 500
:
<TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response> <Step> <Name>ReturnError</Name> <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition> </Step> </Response> </PreFlow> <HTTPTargetConnection> <Properties> <Property name="success.codes">1xx,2xx,3xx,400,500</Property> </Properties> <URL>http://weather.yahooapis.com</URL> </HTTPTargetConnection> </TargetEndpoint>
Konfigurasi TargetEndpoint ini menyebabkan kebijakan yang disebut ReturnError
menangani
respons setiap kali TargetEndpoint menemukan kode respons HTTP
400
ATAU 500
.
Taksonomi kesalahan
API Services mengelompokkan kesalahan ke dalam kategori dan subkategori berikut.
Kategori | Subkategori | Nama Kesalahan | Deskripsi |
---|---|---|---|
Pesan | Kegagalan yang terjadi selama alur pesan (tidak termasuk kegagalan kebijakan) | ||
Kesalahan kustom | {fault_name} | Setiap kesalahan yang ditangani secara eksplisit oleh proxy API menggunakan kebijakan RaiseFault | |
Kode respons | InternalServerError, NotFound | Kode error HTTP 5xx , 4xx |
|
Kegagalan perutean | NoRoutesMatched | Gagal memilih TargetEndpoint bernama untuk permintaan | |
Kegagalan klasifikasi | NotFound | Kegagalan yang disebabkan oleh URI permintaan yang tidak cocok dengan BasePath untuk konfigurasi ProxyEndpoint apa pun (yaitu, tidak ada proxy API yang cocok dengan URL dalam permintaan aplikasi klien) | |
Transportasi | Error tingkat transportasi HTTP | ||
Konektivitas | ConnectionRefused, ConnectionReset, ConnectionTimeout | Kegagalan terjadi saat membuat koneksi tingkat jaringan atau transportasi | |
Minta validasi | ContentLengthMissing, HostHeaderMissing | Kesalahan terjadi selama pemeriksaan semantik pada setiap permintaan | |
Validasi respons | Kesalahan terjadi selama pemeriksaan semantik pada setiap respons | ||
Error IO | SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError | Error baca/tulis di endpoint klien atau target, waktu tunggu habis, error TLS/SSL, dan error berpotongan | |
Sistem | Error runtime yang tidak terdefinisi | ||
Memori | OutOfMemory, GCOverLimit | Kegagalan terkait memori | |
Rangkaian pesan | RogueTaskTerminated | Kegagalan seperti penghentian tugas yang tidak terkendali | |
Kebijakan | Kesalahan untuk setiap jenis kebijakan ditentukan dalam Referensi kebijakan. |
Error selalu disertai dengan deskripsi teks tentang alasan kegagalan. Saat sistem memunculkan kesalahan, serangkaian atribut akan diisi untuk membantu pemecahan masalah. Kesalahan mencakup informasi berikut:
- Alasan
- Atribut kustom yang ditentukan pengguna