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 bisa menggunakan RaiseFault
kebijakan untuk menyetel variabel alur yang terkait dengan kesalahan, seperti fault.name
, fault.type
,
dan fault.category
. Karena variabel ini terlihat dalam data analisis dan log Akses router
digunakan untuk {i>debugging<i}, maka penting untuk
mengidentifikasi kesalahan secara akurat.
Anda dapat menggunakan kebijakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya telah
tidak terjadi di kebijakan lain atau di server backend proxy API. Misalnya, jika Anda ingin
proxy untuk mengirim pesan kesalahan khusus ke aplikasi klien setiap kali respons backend
body berisi string unavailable
, maka Anda dapat memanggil kebijakan RaiseFault sebagai
yang ditampilkan 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 terlihat sebagai fault.name
di
Pemantauan API dan sebagai x_apigee_fault_policy
di log akses Analytics dan Router.
Hal ini akan membantu mendiagnosis penyebab error dengan mudah.
Anti-pola
Menggunakan kebijakan RaiseFault dalam FaultRules setelah kebijakan lain menampilkan error
Perhatikan contoh di bawah, saat kebijakan OAuthV2 dalam alur Proxy API gagal dengan InvalidAccessToken
{i>error<i}. Jika gagal, Edge akan menyetel fault.name
sebagai InvalidAccessToken
, masuk ke
alur error, dan mengeksekusi FaultRules yang ditentukan. Di FaultRule, ada kebijakan RaiseFault bernama
RaiseFault
yang mengirim respons error yang disesuaikan setiap kali InvalidAccessToken
terjadi kesalahan. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti bahwa fault.name
variabel 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 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 adalah fault.name
, fault.code
,
dan fault.policy
akan ditimpa dengan nama kebijakan RaiseFault. Perilaku ini membuat
hampir tidak mungkin untuk menentukan kebijakan mana yang
benar-benar menyebabkan kegagalan tanpa mengakses jejak
file yang menunjukkan kegagalan atau
melakukan reka ulang masalah.
Menggunakan kebijakan RaiseFault untuk menampilkan respons HTTP 2xx di luar alur error.
Pada contoh di bawah, kebijakan RaiseFault bernama HandleOptionsRequest
dijalankan 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 menampilkan respons ke klien API secara langsung tanpa memproses kebijakan lainnya. Namun, hal ini akan menyebabkan data analitik yang menyesatkan karena variabel kesalahan akan berisi Nama kebijakan RaiseFault, membuat proxy lebih sulit untuk di-debug. Cara yang benar untuk menerapkan perilaku yang diinginkan adalah menggunakan Flow dengan kondisi khusus, seperti yang dijelaskan dalam Menambahkan dukungan CORS.
Dampak
Penggunaan kebijakan RaiseFault seperti yang dijelaskan di atas menyebabkan menimpa variabel kesalahan utama dengan
Nama kebijakan RaiseFault, bukan nama kebijakan yang gagal. Di log Analytics dan NGINX Access,
variabel x_apigee_fault_code
dan x_apigee_fault_policy
akan ditimpa. Dalam Pemantauan API, Fault Code
dan Fault Policy
ditimpa. Perilaku ini mempersulit
pemecahan masalah dan
menentukan kebijakan mana yang merupakan
penyebab kegagalan sebenarnya.
Dalam screenshot di bawah dari Pemantauan API,
Anda dapat melihat bahwa kebijakan Fault Code dan Fault ditimpa ke RaiseFault
generik
nilai, sehingga tidak mungkin untuk menentukan akar masalah kegagalan dari log:
Praktik Terbaik
Ketika kebijakan Edge menimbulkan kesalahan dan Anda ingin menyesuaikan pesan respons kesalahan, menggunakan kebijakan MenetapkanMessage atau JavaScript, bukan kebijakan RaiseFault.
Kebijakan RaiseFault harus digunakan dalam alur non-error. Artinya, hanya gunakan RaiseFault untuk menangani kondisi sebagai error, meskipun error yang sebenarnya tidak terjadi dalam kebijakan atau di server backend Proxy API. Misalnya, Anda dapat menggunakan kebijakan {i>RaiseFault<i} untuk memberi sinyal bahwa input wajib parameter hilang atau memiliki sintaksis yang salah.
Anda juga dapat menggunakan RaiseFault dalam aturan kesalahan jika ingin mendeteksi kesalahan selama pemrosesan kesalahan tersebut. Misalnya, pengendali kesalahan Anda sendiri dapat menyebabkan error yang ingin Anda beri sinyal menggunakan RaiseFault.