Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Kebijakan RaiseFault memungkinkan developer API memulai alur error, menetapkan variabel error dalam pesan isi respons, dan menetapkan kode status respons yang sesuai. Anda juga dapat menggunakan kebijakan RaiseFault untuk menetapkan variabel alur yang berkaitan dengan kesalahan, seperti fault.name
, fault.type
, dan fault.category
. Karena variabel ini terlihat dalam data analisis dan log akses Router yang digunakan untuk proses debug, penting untuk mengidentifikasi kesalahan secara akurat.
Anda dapat menggunakan kebijakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya tidak terjadi di kebijakan lain atau di server backend proxy API. Misalnya, jika Anda ingin proxy mengirim pesan error kustom ke aplikasi klien setiap kali isi respons backend berisi string unavailable
, Anda dapat memanggil kebijakan RaiseFault seperti yang ditunjukkan dalam cuplikan kode di bawah ini:
<!-- /antipatterns/examples/raise-fault-conditions-1.xml --> <TargetEndpoint name="default"> ... <Response> <Step> <Name>RF-Service-Unavailable</Name> <Condition>(message.content Like "*unavailable*")</Condition> </Step> </Response> ...
Nama kebijakan RaiseFault dapat dilihat sebagai fault.name
di
API Monitoring dan sebagai x_apigee_fault_policy
di log akses Analytics dan Router.
Hal ini membantu mendiagnosis penyebab kesalahan dengan mudah.
Antipola
Menggunakan kebijakan RaiseFault dalam FaultRules setelah kebijakan lain memunculkan error
Perhatikan contoh di bawah, tempat kebijakan OAuthV2 di alur Proxy API gagal dengan error InvalidAccessToken
. Jika gagal, Edge akan menyetel fault.name
sebagai InvalidAccessToken
, masuk ke dalam alur error, dan menjalankan FaultRules yang telah ditentukan. Di FaultRule, ada kebijakan RaiseFault bernama RaiseFault
yang mengirimkan respons error yang disesuaikan setiap kali error InvalidAccessToken
terjadi. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti bahwa variabel fault.name
akan ditimpa dan menyamarkan penyebab sebenarnya dari kegagalan.
<!-- /antipatterns/examples/raise-fault-conditions-2.xml --> <FaultRules> <FaultRule name="generic_raisefault"> <Step> <Name>RaiseFault</Name> <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition> </Step> </FaultRule> </FaultRules>
Menggunakan kebijakan RaiseFault di FaultRule dalam semua kondisi
Pada contoh di bawah, kebijakan RaiseFault yang bernama RaiseFault
dijalankan jika fault.name
bukan RaiseFault
:
<!-- /antipatterns/examples/raise-fault-conditions-3.xml --> <FaultRules> <FaultRule name="fault_rule"> .... <Step> <Name>RaiseFault</Name> <Condition>!(fault.name equals "RaiseFault")</Condition> </Step> </FaultRule> </FaultRules>
Seperti dalam skenario pertama, variabel kesalahan utama fault.name
, fault.code
, dan fault.policy
akan ditimpa dengan nama kebijakan RaiseFault. Perilaku ini membuat
hampir tidak mungkin untuk menentukan kebijakan mana yang sebenarnya menyebabkan kegagalan tanpa mengakses file
rekaman aktivitas yang menunjukkan kegagalan atau mereproduksi masalah.
Menggunakan kebijakan RaiseFault untuk menampilkan respons HTTP 2xx di luar alur error.
Pada contoh di bawah, kebijakan RaiseFault yang bernama HandleOptionsRequest
dieksekusi saat kata kerja permintaan adalah OPTIONS
:
<!-- /antipatterns/examples/raise-fault-conditions-4.xml --> <PreFlow name="PreFlow"> <Request> … <Step> <Name>HandleOptionsRequest</Name> <Condition>(request.verb Equals "OPTIONS")</Condition> </Step> … </PreFlow>
Tujuannya adalah untuk segera menampilkan respons ke klien API tanpa memproses kebijakan lain. Namun, hal ini akan menyebabkan data analisis yang menyesatkan karena variabel kesalahan akan berisi nama kebijakan RaiseFault, sehingga proxy lebih sulit untuk di-debug. Cara yang benar untuk mengimplementasikan perilaku yang diinginkan adalah menggunakan Flow dengan kondisi khusus, seperti dijelaskan dalam Menambahkan dukungan CORS.
Dampak
Penggunaan kebijakan RaiseFault seperti yang dijelaskan di atas menyebabkan variabel kesalahan utama ditimpa dengan nama kebijakan RaiseFault, bukan nama kebijakan yang gagal. Di log Analytics dan Akses NGINX,
variabel x_apigee_fault_code
dan x_apigee_fault_policy
akan ditimpa. Dalam API Monitoring, Fault Code
dan Fault Policy
akan ditimpa. Perilaku ini mempersulit pemecahan masalah dan
menentukan kebijakan mana yang merupakan penyebab kegagalan sebenarnya.
Pada screenshot dari API Monitoring di bawah, Anda dapat melihat bahwa kebijakan Fault Code dan Fault ditimpa ke nilai RaiseFault
generik, sehingga mustahil untuk menentukan akar masalah dari log:
Praktik Terbaik
Saat kebijakan Edge memunculkan kesalahan dan Anda ingin menyesuaikan pesan respons error, gunakan kebijakan ProvideMessage atau JavaScript, bukan kebijakan RaiseFault.
Kebijakan RaiseFault harus digunakan dalam alur non-error. Artinya, hanya gunakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya tidak terjadi dalam kebijakan atau server backend Proxy API. Misalnya, Anda dapat menggunakan kebijakan RaiseFault untuk memberikan sinyal bahwa parameter input wajib tidak ada atau memiliki sintaksis yang salah.
Anda juga dapat menggunakan RaiseFault dalam aturan fault jika ingin mendeteksi error selama pemrosesan kesalahan. Misalnya, pengendali fault Anda sendiri dapat menyebabkan error yang ingin Anda beri sinyal menggunakan RaiseFault.