Antipola: Menggunakan Kebijakan RaiseFault dalam kondisi yang tidak tepat

Anda sedang melihat dokumentasi Apigee dan Apigee Hybrid.
Lihat dokumentasi Apigee Edge.

KebijakanRaiseFault 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 sebenarnya belum 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: 

<!-- /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 membantu mendiagnosis penyebab error dengan mudah.

Antipola

Menggunakan kebijakan RaiseFault dalam FaultRules setelah kebijakan lain sudah memunculkan error

Pertimbangkan contoh di bawah, saat kebijakan OAuthV2 dalam alur Proxy API gagal dengan error InvalidAccessToken. Jika gagal, Apigee akan menetapkan fault.name sebagai InvalidAccessToken, masuk ke alur error, dan menjalankan FaultRules yang ditentukan. Di FaultRule, ada kebijakan RaiseFault bernama RaiseFault yang mengirimkan respons error yang disesuaikan setiap kali terjadi error InvalidAccessToken. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti variabel fault.name ditimpa dan menyembunyikan penyebab sebenarnya 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 dalam FaultRule dalam semua kondisi

Dalam contoh di bawah, kebijakan RaiseFault bernama RaiseFault dieksekusi 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 pada skenario pertama, variabel kesalahan utama fault.name, fault.code, dan fault.policy ditimpa dengan nama kebijakan RaiseFault. Perilaku ini hampir tidak memungkinkan 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.

Dalam contoh di bawah, kebijakan RaiseFault 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 membuat proxy lebih sulit di-debug. Cara yang benar untuk menerapkan perilaku yang diinginkan adalah dengan menggunakan Alur dengan kondisi khusus, seperti yang dijelaskan dalam Menambahkan dukungan CORS.

Dampak

Penggunaan kebijakan RaiseFault seperti yang dijelaskan di atas akan mengakibatkan penimpaan variabel kesalahan utama dengan nama kebijakan RaiseFault, bukan nama kebijakan yang gagal. Di log Akses Analytics dan NGINX, variabel x_apigee_fault_code dan x_apigee_fault_policy ditimpa. Di API Monitoring, Fault Code dan Fault Policy akan diganti. Perilaku ini menyulitkan pemecahan masalah dan penentuan kebijakan mana yang menjadi penyebab sebenarnya kegagalan.

Pada screenshot di bawah dari Pemantauan API, Anda dapat melihat bahwa Kode Kesalahan dan kebijakan Kesalahan diganti dengan nilai RaiseFault generik, sehingga tidak mungkin untuk menentukan penyebab utama kegagalan dari log:

Ditentukan Nanti

Praktik Terbaik

Saat kebijakan Apigee memunculkan kesalahan dan Anda ingin menyesuaikan pesan respons error, gunakan kebijakan AssignMessage atau JavaScript, bukan kebijakan RaiseFault.

Kebijakan RaiseFault harus digunakan dalam alur non-error. Artinya, gunakan RaiseFault hanya untuk memperlakukan kondisi tertentu sebagai error, meskipun error sebenarnya belum terjadi dalam kebijakan atau di server backend Proxy API. Misalnya, Anda dapat menggunakan kebijakan RaiseFault untuk menandakan bahwa parameter input wajib tidak ada atau memiliki sintaksis yang salah.

Anda juga dapat menggunakan RaiseFault dalam aturan kesalahan jika ingin mendeteksi error selama pemrosesan kesalahan. Misalnya, handler kesalahan Anda sendiri dapat menyebabkan error yang ingin Anda beri sinyal menggunakan RaiseFault.

Bacaan lebih lanjut