Halaman ini diterjemahkan oleh Cloud Translation API.

Antipola: Menggunakan Kebijakan RaiseFault dalam kondisi yang tidak pantas

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

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 error, 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 menampilkan error

Pertimbangkan contoh di bawah, saat kebijakan OAuthV2 dalam alur Proxy API gagal dengan error InvalidAccessToken. Setelah 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 error InvalidAccessToken terjadi. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti variabel fault.name 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 dalam FaultRule dalam semua kondisi

Dalam contoh di bawah, kebijakan RaiseFault bernama RaiseFault akan 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 dalam skenario pertama, variabel error utama fault.name, fault.code, dan fault.policy 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.

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 error akan berisi nama kebijakan RaiseFault, sehingga proxy lebih sulit 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 akan menimpa variabel error utama dengan nama kebijakan RaiseFault, bukan nama kebijakan yang gagal. Dalam log Akses Analytics dan NGINX, variabel x_apigee_fault_code dan x_apigee_fault_policy ditimpa. Di Pemantauan API, Fault Code dan Fault Policy ditimpa. Perilaku ini mempersulit pemecahan masalah dan menentukan kebijakan mana yang merupakan penyebab sebenarnya dari kegagalan.

Pada screenshot di bawah dari Pemantauan API, Anda dapat melihat bahwa Kebijakan Fault dan Kode Error ditimpa dengan nilai RaiseFault generik, sehingga tidak dapat menentukan akar penyebab kegagalan dari log:

Praktik Terbaik

Saat kebijakan Apigee memunculkan error dan Anda ingin menyesuaikan pesan respons error, gunakan kebijakan AssignMessage 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 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 error jika ingin mendeteksi error selama pemrosesan error. Misalnya, pengendali error itu sendiri dapat menyebabkan error yang ingin Anda sinyal dengan menggunakan RaiseFault.