Menangani kesalahan

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Banyak kondisi error yang dapat muncul saat proxy API melayani permintaan dari aplikasi. Misalnya, proxy API mungkin mengalami masalah jaringan saat berkomunikasi dengan layanan backend, aplikasi mungkin menunjukkan kredensial yang sudah tidak berlaku, pesan permintaan mungkin salah diformat, dan seterusnya.

Jika terjadi error setelah aplikasi klien memanggil proxy API, pesan error akan ditampilkan ke klien. Secara default, klien sering menerima pesan error samar tanpa detail atau panduan. Namun, jika Anda ingin mengganti pesan error default dengan pesan kustom yang lebih berguna, bahkan memperkayanya dengan hal-hal seperti header HTTP tambahan, Anda perlu menyiapkan penanganan kesalahan kustom di Edge.

Penanganan kesalahan kustom juga memungkinkan Anda menambahkan fungsi seperti logging pesan setiap kali terjadi error.

Sebelum membahas cara menerapkan penanganan error kustom untuk proxy API Anda, sebaiknya pahami error yang terjadi dan reaksi proxy API terhadapnya.

Video

Tonton video berikut untuk mempelajari lebih lanjut tentang penanganan kesalahan.

Video Deskripsi
Pengantar penanganan fault dan alur error Pelajari penanganan kesalahan dan hal yang terjadi jika terjadi error di proxy API.
Menangani error menggunakan aturan fault Pelajari cara menangani kesalahan menggunakan aturan fault.
Meningkatkan kesalahan kustom menggunakan kebijakan RaiseFault Meningkatkan kesalahan kustom selama runtime API menggunakan kebijakan RaiseFault.
Menentukan aturan fault di proxy API dan endpoint target Tentukan aturan fault di proxy API dan endpoint target, serta pahami perbedaannya.
Memahami urutan eksekusi aturan fault Pahami urutan eksekusi aturan fault di proxy API dan endpoint target.
Menentukan aturan fault default Menentukan aturan kesalahan default untuk menangani error umum di API Anda.

Cara terjadinya error

Pertama-tama, kita hanya akan membahas bagaimana error terjadi. Mengetahui bagaimana error terjadi akan membantu Anda merencanakan berbagai situasi ketika Anda ingin menerapkan penanganan error kustom.

Error otomatis

Proxy API melempar error secara otomatis dalam situasi berikut:

  • Kebijakan memunculkan error. Misalnya, jika panggilan API mengirim kunci yang sudah tidak berlaku, kebijakan VerifyAPIKey akan otomatis menampilkan error; atau jika jumlah panggilan API melebihi batas tertentu, Kebijakan kuota atau kebijakan SpikeArrest akan menampilkan error. (Lihat Referensi error kebijakan untuk jenis-jenis error yang dapat ditampilkan oleh kebijakan).
  • Terdapat 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 yang tidak tersedia.
  • Ada kegagalan tingkat sistem, seperti pengecualian kehabisan memori.

Untuk mengetahui informasi lebih lanjut tentang error ini, lihat Taksonomi kesalahan dalam topik ini.

Error kustom

Jika tidak ada error otomatis, Anda dapat menampilkan error kustom; misalnya, jika respons berisi kata "unavailable", atau jika kode status HTTP lebih besar dari 201. Lakukan hal 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 pada 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 menampilkan error kustom. Kami membahas kebijakan RaiseFault secara lebih mendetail di bagian kebijakan FaultRules vs. RaiseFault.

Untuk contoh lainnya, lihat postingan berikut di Forum Komunitas Apigee:

Apa yang dilakukan proxy API saat terjadi error

Inilah yang terjadi ketika proxy menampilkan error.

Keluar dari pipeline proxy

Saat proxy API mengalami error, terlepas dari caranya, proxy 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, anggaplah proxy API memiliki kebijakan dengan urutan berikut pada permintaan ProxyEndpoint:

  1. Memverifikasi Kunci API
  2. Kuota
  3. JSON ke XML

Jika terjadi error selama verifikasi kunci API, proxy API akan beralih ke status error. Kebijakan Kuota dan JSON ke XML tidak dijalankan, proxy tidak akan melanjutkan ke TargetEndpoint, dan pesan error ditampilkan ke aplikasi klien.

Memeriksa FaultRules

Dalam status error, proxy API juga memeriksa keberadaan hal-hal berikut (secara berurutan) dalam konfigurasi proxy API sebelum menampilkan pesan error default ke aplikasi klien:

  1. Bagian <FaultRules>, yang berisi logika untuk memicu pesan error kustom (dan kebijakan lainnya) berdasarkan kondisi tertentu yang Anda tentukan.
  2. Bagian <DefaultFaultRule>, yang memicu pesan error default dalam situasi berikut:
    • Tidak ada <FaultRules> yang ditentukan.
    • Tidak ada <FaultRules> yang dijalankan.
    • Elemen <AlwaysEnforce> disetel ke benar (true).

Pada dasarnya, proxy API memberi Anda kesempatan untuk menampilkan pesan error kustom dan memicu logika lainnya. Jika proxy menemukan kedua bagian tersebut, atau keduanya ada tetapi tidak ada kesalahan khusus yang dipicu, proxy akan mengirimkan pesan default yang dihasilkan Edge-nya sendiri.

Contoh penanganan kesalahan sederhana

Mari kita mulai dengan contoh sederhana, ketika 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 menemukan pesan error, tetapi mungkin tidak. Selain itu, banyak error default yang lebih halus dan sulit untuk dipahami.

Sebagai developer API, Anda dapat mengubah pesan ini untuk memenuhi kebutuhan siapa pun yang pada akhirnya akan menerima pesan error, baik itu developer aplikasi iOS atau grup pengujian internal yang memiliki persyaratan format pesan error sendiri.

Berikut adalah contoh dasar tentang cara membuat pesan error khusus untuk menangani error ini. Hal ini memerlukan 1) kebijakan yang menentukan pesan kustom, dan 2) FaultRule yang menjalankan kebijakan saat proxy mengalami status error.

1. Buat kebijakan yang mendefinisikan pesan kustom

Pertama, buat kebijakan yang menetapkan pesan error kustom. Anda dapat menggunakan jenis kebijakan apa pun, seperti kebijakanAssignMessage, yang dapat menetapkan payload dan header HTTP opsional seperti kode status dan frasa alasan. Opsi Tetapkan Pesan sangat ideal untuk hal ini. Solusi ini memungkinkan Anda mengontrol payload pesan, menetapkan kode status HTTP yang berbeda, menetapkan frasa alasan HTTP yang berbeda, dan menambahkan header HTTP.

Jangan lampirkan kebijakan ke alur apa pun di proxy API. Instance tersebut cukup ada di paket proxy. Untuk melakukannya di editor proxy UI pengelolaan, buka tab Pengembangan, lalu di panel Navigasi, lalu klik ikon + pada panel Kebijakan.

Hal ini memungkinkan Anda membuat kebijakan tanpa melampirkannya ke flow di proxy API. Kebijakan yang tidak dilampirkan ke flow apa pun akan ditandai dengan ikon "terpisah" dalam daftar Kebijakan, seperti yang ditampilkan di sebelah kebijakan pesan kunci API yang ditampilkan di gambar sebelumnya.

Berikut adalah contoh kebijakanAssignMessage yang:

  • Menampilkan pesan JSON.
  • Menetapkan kode status HTTP (911, yang merupakan kode status yang jelas tidak ada hanya untuk menggambarkan fleksibilitas yang Anda miliki). Kode status muncul di header HTTP.
  • Menetapkan frasa alasan HTTP (untuk mengganti frasa alasan "Tidak sah" default untuk error kunci API yang tidak ada ini). Frasa alasan muncul di samping kode status 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>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Saat kebijakan ini dijalankan, respons terhadap aplikasi klien akan terlihat seperti berikut. Bandingkan dengan respons default yang ditunjukkan 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! Call the cops!
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, ini sedikit konyol, tetapi hal itu menunjukkan kepada Anda apa yang mungkin terjadi. Setidaknya sekarang developer yang menerima pesan mengetahui bahwa mereka lupa menyertakan kunci API sebagai parameter kueri.

Namun, bagaimana kebijakan ini dijalankan? 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> individual. Setiap FaultRule mewakili 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 FaultRules Anda 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. Lebih lanjut lagi tentang menempatkan FaultRules di ProxyEndpoint vs. TargetEndpoint nanti.
  • <Name> - Nama kebijakan yang akan dijalankan. Nama ini berasal dari atribut name kebijakan pada elemen induk, seperti ditunjukkan dalam contoh kebijakan sebelumnya.
  • <Condition> - Edge mengevaluasi kondisi dan mengeksekusi kebijakan hanya jika kondisinya benar. Jika ada beberapa FaultRules yang bernilai benar, Edge akan mengeksekusi aturan pertama yang benar. (Penting: Urutan FaultRules dievaluasi, dari atas ke bawah atau dari bawah ke atas, berbeda antara TargetEndpoint dan ProxyEndpoint, seperti yang dijelaskan di bagian Beberapa FaultRules dan logika eksekusi.) Jika Anda tidak menyertakan sebuah kondisi, FaultRule akan otomatis bernilai true. Tapi itu bukan praktik terbaik. Setiap FaultRule harus memiliki kondisinya sendiri.

  • <DefaultFaultRule> - Jika tidak ada FaultRule kustom yang dijalankan, <DefaultFaultRule> akan dijalankan, sehingga mengirim pesan kustom yang lebih umum, bukan pesan default samar yang dibuat Edge. <DefaultFaultRule> juga dapat memiliki <Condition>, tetapi dalam sebagian besar kasus, Anda tidak akan menyertakannya, karena Anda ingin elemen tersebut dijalankan, apa pun opsinya sebagai upaya terakhir.

    DefaultFaultRule biasanya digunakan untuk menampilkan pesan error umum untuk error yang tidak terduga. Contohnya adalah pesan yang berisi informasi kontak untuk dukungan teknis. Respons default ini memiliki tujuan ganda, yaitu memberikan informasi yang cocok untuk developer sekaligus mengaburkan URL backend atau informasi lain yang mungkin digunakan untuk membahayakan sistem.

Multiple FaultRules dan logika eksekusi

Di bagian Contoh penanganan fault sederhana, kami menggunakan contoh sederhana satu FaultRule dan kondisi. Dalam project API dunia nyata, dengan semua kemungkinan error yang dapat terjadi, Anda kemungkinan akan memiliki beberapa FaultRules dan DefaultFaultRule di <ProxyEndpoint> dan <TargetEndpoint>. Pada akhirnya, hanya satu FaultRule yang dijalankan ketika proxy API mengalami status error.

Bagian ini menjelaskan logika yang digunakan Edge dalam menangani FaultRules, mulai dari cara kode tersebut diterima di satu FaultRule untuk dieksekusi, hingga cara kondisi Langkah "dalam" ditangani saat FaultRule dipicu. Bagian ini juga memberikan panduan tentang kapan harus menentukan FaultRules di <ProxyEndpoint> vs. <TargetEndpoint>, serta menjelaskan hubungan antara FaultRules dan kebijakan RaiseFault.

Eksekusi FaultRules

Singkatnya, berikut ini logika yang digunakan Edge saat proxy API masuk ke status error. Perhatikan bahwa ada sedikit perbedaan antara evaluasi FaultRules di ProxyEndpoint dengan TargetEndpoint.

  1. Edge mengevaluasi FaultRules di ProxyEndpoint atau TargetEndpoint, bergantung pada tempat terjadinya error:
    • ProxyEndpoint - Edge dimulai dengan <FaultRule> bottom dalam XML konfigurasi dan bekerja hingga ke atas, sehingga mengevaluasi <Condition> dari setiap <FaultRule> (kondisi "luar", bukan kondisi <Step> "dalam").
    • TargetEndpoint - Edge dimulai dengan <FaultRule> top dalam XML konfigurasi dan menuju ke bawah, mengevaluasi <Condition> dari setiap <FaultRule> (kondisi "luar", bukan kondisi <Step> "dalam").
  2. Mengeksekusi FaultRule first yang kondisinya benar. Jika FaultRule tidak memiliki kondisi, nilainya akan menjadi true secara default.
    • Saat FaultRule dijalankan, semua Langkah di dalam FaultRule akan dievaluasi secara berurutan, dari atas ke bawah dalam konfigurasi XML. Langkah tanpa kondisi akan otomatis dijalankan (kebijakan akan dijalankan), dan Langkah yang memiliki <Condition> yang bernilai "true" akan dijalankan (kondisi yang bernilai "false" tidak akan dijalankan).
    • Jika FaultRule dijalankan, tetapi tidak ada Langkah di FaultRule yang dijalankan (karena kondisinya bernilai "false"), pesan error default yang dihasilkan Edge akan ditampilkan ke aplikasi klien. <DefaultFaultRule> tidak dijalankan, karena Edge sudah menjalankan satu FaultRule-nya.

  3. Jika FaultRule tidak dijalankan, Edge akan mengeksekusi <DefaultFaultRule>, jika ada.

Berikut adalah contoh dengan komentar inline.

Eksekusi ProxyEndpoint

Evaluasi ProxyEndpoint FaultRules dilakukan dari bawah ke atas, jadi mulailah membaca di 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), Edge
     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, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge 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 Edge 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 pada FaultRule pertama dalam contoh berikut dan lanjutkan ke bawah. Lihat DefaultFaultRule terakhir.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge 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), Edge
     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 Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Urutan aturan kesalahan

Seperti yang Anda lihat pada contoh sebelumnya, urutan penempatan FaultRules penting, bergantung pada apakah terjadi error di ProxyEndpoint atau TargetEndpoint.

Contoh:

Urutan ProxyEndpoint Urutan TargetEndpoint

Pada contoh berikut, karena evaluasi dilakukan dari bawah ke atas, FaultRule 3 dijalankan, yang berarti FaultRules 2 dan 1 tidak dievaluasi.

5. FaultRule 1: FALSE

4. Aturan Kesalahan 2: BENAR

3. Aturan Kesalahan 3: BENAR

2. FaultRule 4: FALSE

1. FaultRule: 5 SALAH

Pada contoh berikut, karena evaluasi dilakukan dari atas ke bawah, FaultRule 2 dijalankan, yang berarti FaultRules 3, 4, dan 5 tidak dievaluasi.

1. FaultRule 1: FALSE

2. Aturan Kesalahan 2: BENAR

3. Aturan Kesalahan 3: BENAR

4. FaultRule 4: FALSE

5. FaultRule: 5 SALAH

Kebijakan yang akan disertakan

Anda dapat menjalankan kebijakan apa pun dari FaultRule dengan menempatkannya di Langkah. Misalnya, Anda dapat menjalankan kebijakanAssignMessage untuk memformat respons terhadap aplikasi klien, lalu mencatat pesan ke dalam log dengan kebijakan MessageLogging. Kebijakan dijalankan sesuai urutan yang Anda tentukan (dari atas ke bawah dalam XML).

Aturan kesalahan HANYA dipicu dalam status error (tentang continueOnError)

Judul mungkin tampak seperti kita ulangi, tetapi ada satu nuansa tertentu yang perlu diperhatikan sehubungan dengan error proxy yang menyebabkan proxy API memasuki status error—atau lebih tepatnya, tidak memasuki status error: atribut continueOnError pada suatu kebijakan.

Ringkasnya: Proxy API akan mengevaluasi <FaultRules> dan <DefaultFaultRule> hanya jika proxy tersebut memasuki status error. Artinya, meskipun jika kondisi FaultRule dievaluasi ke true, kondisi tersebut tidak akan dipicu jika proxy tidak dalam status error.

Namun, berikut adalah 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 tersebut sangat penting terkait dengan penanganan fault, karena menentukan apakah proxy memasuki status error atau tidak jika kebijakan gagal. Pada umumnya, Anda dapat mempertahankan continueOnError="false" default, yang menempatkan proxy dalam status error jika kebijakan gagal, dan penanganan error kustom Anda akan dipicu. Namun, jika continueOnError="true" (misalnya, jika Anda tidak ingin kegagalan Pemanggilan Layanan menghentikan eksekusi proxy), proxy tidak akan mengalami status error jika kebijakan tersebut gagal, dan proxy tidak akan melihat FaultRules Anda.

Untuk mengetahui informasi tentang logging error saat continueOnError="true", lihat Menangani kesalahan kebijakan dalam flow saat ini.

Tempat menentukan FaultRules: ProxyEndpoint atau TargetEndpoint

Saat proxy API mengalami error, error tersebut akan terjadi dalam <ProxyEndpoint> (permintaan dari atau respons terhadap aplikasi klien) atau dalam <TargetEndpoint> (permintaan ke atau respons dari layanan target). Di mana pun error itu terjadi, adalah tempat Edge mencari FaultRules.

Misalnya, jika server target tidak tersedia (kode status HTTP 503), proxy API akan mengalami status error dalam respons <TargetEndpoint>, dan alur proxy API normal tidak akan berlanjut ke <ProxyEndpoint>. Jika Anda hanya menentukan FaultRules dalam <ProxyEndpoint>, FaultRules tidak akan menangani error tersebut.

Contoh lainnya, Jika kebijakan RaiseFault pada respons <ProxyEndpoint> memicu error, FaultRule dalam <TargetEndpoint> tidak akan dijalankan.

Kebijakan FaultRules vs. RaiseFault

Aturan kesalahan dan kebijakan RaiseFault mungkin terdengar seperti cara alternatif untuk menyelesaikan penanganan fault; dan dalam beberapa hal ini memang benar. Tetapi mereka juga bekerja sama. Bagian ini menjelaskan hubungan antara keduanya. Memahami hubungan ini akan membantu Anda mendesain penanganan kesalahan, terutama jika ingin menggunakan keduanya.

Singkatnya:

  • Aturan kesalahan selalu dievaluasi saat proxy API memasuki status error.
  • Kebijakan RaiseFault adalah cara untuk menempatkan proxy API dalam status error ketika error sebenarnya tidak terjadi.

    Misalnya, jika ingin menampilkan error jika kode status HTTP dalam respons dari layanan target lebih besar dari 200, Anda harus menambahkan kebijakan RaiseFault dalam alur respons. Tampilan 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 mengirim pesan error ke aplikasi klien.

Apa yang terjadi saat kebijakan RaiseFault memicu error, yang menempatkan proxy dalam status error, dan berpotensi menjalankan FaultRule? Di sinilah segalanya akan menjadi sedikit rumit. Jika kebijakan RaiseFault menampilkan pesan error dan FaultRule terpicu dan menampilkan pesan error, apa yang ditampilkan ke aplikasi klien?

  • Karena FaultRule atau DefaultFaultRule dijalankan setelah kebijakan RaiseFault, data respons FaultRule akan menang.
  • Data respons kebijakan RaiseFault (kode status, frasa alasan, atau payload pesan) digunakan jika data tersebut tidak disetel 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 hal yang ditetapkan oleh kebijakan RaiseFault dan FaultRule, serta apa saja yang ditampilkan ke aplikasi klien. Contoh ini dirancang agar singkat, bukan untuk praktik terbaik.

Aplikasi klien menerima:

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

<- Kebijakan aturan kesalahan menetapkan hal ini:

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

<- Kebijakan RaiseFault menetapkan hal ini:

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Membuat kondisi

Kondisi adalah kunci untuk eksekusi FaultRule. Anda membuat kondisi FaultRule dengan cara yang sama seperti yang Anda lakukan untuk kondisi lain di Edge, misalnya untuk flow kondisional atau kondisi RaiseFault.

Untuk memasukkan bagian lainnya dalam konteks, berikut adalah contoh aturan fault yang memiliki kondisi FaultRule luar dan kondisi Step bagian 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 menampilkan error.

fault.name

Jika kebijakan gagal, tangkap error dalam kondisi menggunakan variabel fault.name. Contoh:

<Condition>(fault.name = "policy_error_name")</Condition>

Nama error akan muncul di pesan error default. Misalnya, dalam hal berikut, nama kesalahan adalah FailedToResolveAPIKey. Dalam hal ini, variabel flow 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 error kebijakan untuk melihat daftar error kebijakan.

{policy_namespace}.{policy_name}.gagal

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.

Variabel lain yang tersedia

Ketika 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 ditampilkan dalam respons, FaultRule dalam <TargetEndpoint> dapat menggunakan data HTTP response.status.code, message.content, error.content, dan seterusnya. Atau, jika Kebijakan kuota gagal, Anda dapat menggunakan variabel ratelimit.{quota_policy_name}.exceed.count. Gunakan alat Pelacakan dan topik referensi kebijakan untuk membantu Anda mengetahui variabel dan data HTTP yang tersedia.

Informasi selengkapnya

  • Kondisi: Referensi kondisi serta Variabel dan kondisi flow

  • Error: Referensi error kebijakan
  • Variabel: Referensi variabel, lalu lihat halaman referensi kebijakan individual untuk variabel yang tersedia dengan masing-masing kebijakan.

Praktik terbaik untuk penanganan fault

Penanganan kesalahan adalah tugas desain arsitektur utama untuk pengembangan proxy API. Anda harus meluangkan waktu untuk mencari tahu bagaimana dan kapan Anda akan menangani error, menentukan pesan error yang akan muncul, dan merancang format pesan error. Setelah (atau sesuai) Anda menyelesaikan masalah tersebut, gunakan praktik terbaik ini untuk membantu Anda mengimplementasikan penanganan fault.

Berikut adalah beberapa praktik terbaik dalam mendesain dan membuat penanganan fault:

  • Untuk setiap FaultRule, berikan <Condition> "outer" (seinduk dengan elemen <Step>). Aturan error tanpa kondisi luar akan otomatis dievaluasi ke true. Kondisi Langkah "Inner" tidak digunakan untuk menentukan apakah FaultRule benar atau salah. Kondisi langkah hanya dievaluasi setelah Edge menjalankan FaultRule yang memuatnya. Dalam FaultRule, biasanya ada beberapa Langkah dengan kebijakan Tetapkan Pesan (atau lainnya), masing-masing dengan kondisi Langkah.
  • Untuk menangani error di beberapa kebijakan dari jenis yang sama (misalnya, beberapa kebijakan Kuota), buat satu FaultRule untuk setiap error kebijakan yang kemungkinan akan Anda terima. Misalnya, buat FaultRule untuk setiap kemungkinan error dalam kebijakan Kuota, seperti QuotaViolation, InvalidMessageWeight, StartTimeNotSupported. (Lihat Referensi error kebijakan untuk error kebijakan. Saat menemukan error lain yang perlu ditangani, Anda dapat kembali lagi nanti dan menambahkannya ke FaultRules. Anda dapat melakukan iteratif, meskipun memang memerlukan deployment ulang proxy.) Pendekatan ini memungkinkan Anda menangkap jenis error yang sama, apa pun kebijakan yang memunculkannya, sehingga XML FaultRules Anda efisien.

    Kemudian gunakan kondisi Langkah internal jika Anda memerlukan kontrol error yang lebih mendetail. Misalnya, jika Anda menerapkan kuota developer individual dan kuota global dengan dua kebijakan dalam alur permintaan Anda, tetapkan kondisi FaultRule "outer" agar dipicu pada error QuotaViolation (yang ditampilkan ketika kuota terlampaui dalam kedua kasus). Kemudian, tetapkan kondisi Langkah untuk mengevaluasi variabel exceed.count di kedua kebijakan kuota Anda. Hanya error yang relevan yang akan dikirim ke klien (kelebihan kuota developer atau kelebihan kuota global). Berikut adalah contoh konfigurasi ini:

    <FaultRule name="over_quota">
    <!-- This condition catches a QuotaViolation in *any* Quota policy -->
      <Condition>(fault.name = "QuotaViolation")</Condition>
      <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>
    </FaultRule>
    

    Untuk contoh lainnya, lihat rangkaian pesan Komunitas Apigee ini.

  • Untuk menangani error ketika Anda menggunakan satu kebijakan dari satu jenis, pertimbangkan satu aturan kesalahan yang dijalankan ketika satu kebijakan tersebut gagal, dan sertakan beberapa langkah yang memetakan ke setiap kemungkinan error. Hal ini membuat XML Anda tetap efisien dengan menggunakan satu FaultRule, bukan beberapa FaultRules (satu untuk setiap jenis error). Contoh:

    <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>Generic-Key-Fault</Name>
      </Step>
      <Step>
        <Name>Assign-Message-Raise-Fault-1</Name>
        <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
      </Step>
      <Step>
        <Name>Assign-Message-Raise-Fault-2</Name>
        <Condition>(fault.name = "InvalidApiKey")</Condition>
      </Step>
    </FaultRule>
    
  • Tambahkan FaultRules tempat error akan terjadi (sisi klien <ProxyEndpoint> atau sisi target <TargetEndpoint>). Sertakan FaultRules untuk setiap kebijakan yang muncul di setiap lokasi.
  • Di FaultRules, Anda dapat menjalankan jenis kebijakan apa pun yang dapat menampilkan pesan ke aplikasi klien. KebijakanAssignMessage sangat ideal untuk hal ini. Pertimbangkan juga untuk mencatat pesan ke dalam log dengan kebijakan MessageLogging jika Anda ingin melacak error.
  • Saat menggunakan kebijakan RaiseFault bersama dengan FaultRules, koordinasikan data respons yang dikirim kembali saat kebijakan RaiseFault dan FaultRule menampilkan data. Misalnya, jika kebijakan RaiseFault Anda mereset kode status HTTP, FaultRule tidak akan mereset kode status. Hal terburuk yang dapat terjadi adalah kode status default ditampilkan ke aplikasi klien.
  • Eksekusi <DefaultFaultRule>:
    • Jika Anda ingin <DefaultFaultRule> selalu dijalankan saat tidak ada FaultRule lain yang dieksekusi, jangan sertakan <Condition> di dalamnya.
    • Jika Anda ingin <DefaultFaultRule> selalu dieksekusi meskipun FaultRule lain telah dieksekusi, tambahkan elemen turunan <AlwaysEnforce>true</AlwaysEnforce>.

Pola untuk penanganan kesalahan yang terpusat dan dapat digunakan kembali

Postingan Komunitas Apigee berikut menjelaskan pola penanganan kesalahan terpusat tanpa duplikasi kode:

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

Membuat FaultRules

Untuk menambahkan FaultRule, Anda perlu mengedit konfigurasi XML ProxyEndpoint atau TargetEndpoint. Anda dapat menggunakan UI Edge untuk melakukan pengeditan ini di panel Code di tampilan Develop untuk proxy API, atau edit file XML yang menentukan ProxyEndpoint atau TargetEndpoint.

Jika Anda membuat FaultRules di UI pengelolaan, 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 dapat menempatkan kebijakan apa pun di FaultRule, Anda biasanya menggunakan kebijakanAssignMessage untuk membuat pesan respons kustom untuk kondisi error. Dengan TetapkanMessage, Anda dapat mengonfigurasi respons HTTP dengan payload, kode status HTTP, header, dan elemen frasa alasan.

Contoh di bawah menunjukkan konfigurasi kebijakanAssignMessage yang umum:

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Anda kini dapat menggunakan kebijakan ini di FaultRule. Perhatikan cara Anda mereferensikan kebijakan ProvideMessage berdasarkan nama di FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Saat Anda men-deploy konfigurasi di atas, proxy API akan mengeksekusi kebijakan TetapkanMessage yang disebut fault_invalidkey setiap kali aplikasi menampilkan kunci API yang tidak valid.

Anda dapat menjalankan beberapa kebijakan di FaultRule, seperti yang ditunjukkan contoh berikut:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Kebijakan dieksekusi dalam urutan yang ditentukan. Misalnya, Anda dapat menggunakan kebijakan MessageLogging, kebijakan ExtractVariables, kebijakanAssignMessage, atau kebijakan lainnya di FaultRule. Perhatikan bahwa pemrosesan FaultRule akan langsung berhenti jika salah satu situasi berikut terjadi:

  • Kebijakan apa pun di FaultRule menyebabkan error
  • Salah satu kebijakan di FaultRule adalah jenis RaiseFault

Menentukan pesan error kustom yang ditampilkan dari FaultRule

Sebagai praktik terbaik, Anda harus menentukan respons error yang jelas dari API Anda. Dengan cara itu, Anda memberikan informasi yang konsisten dan bermanfaat kepada klien Anda.

Contoh kebijakanAssignMessage berikut menggunakan tag <Payload>, <StatusCode>, dan <ReasonPhase> untuk menentukan respons error kustom yang dikirim kembali ke klien pada error InvalidApiKey (lihat contoh FaultRules sebelumnya).

<AssignMessage name="fault_invalidkey">
  <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>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Respons ini berisi:

  • Payload yang berisi pesan error dan alamat email untuk menghubungi dukungan.
  • Kode status HTTP yang ditampilkan dalam respons.
  • Frasa alasan, yang merupakan deskripsi singkat error.

Membuat DefaultFaultRule

DefaultFaultRule bertindak sebagai pengendali pengecualian untuk error yang tidak ditangani secara eksplisit oleh FaultRule lain. Jika kondisi untuk semua FaultRules tidak cocok dengan error, DefaultFaultRule akan menangani error tersebut. Aktifkan penanganan fault default dengan menambahkan tag <DefaultFaultRule> sebagai elemen turunan dari ProxyEndpoint atau TargetEndpoint.

Misalnya, konfigurasi TargetEndpoint di bawah ini menentukan DefaultFaultRule yang memanggil kebijakan bernama ReturnGenericError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.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 cocok untuk developer sekaligus mengaburkan URL backend atau informasi lain yang mungkin digunakan untuk menyusupi sistem.

Misalnya, Anda menentukan kebijakan ProvideMessage berikut untuk menampilkan error generik:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Sertakan elemen <AlwaysEnforce> dalam tag <DefaultFaultRule> guna menjalankan DefaultFaultRule untuk setiap error, meskipun FaultRule lain telah dijalankan. DefaultFaultRule selalu menjadi FaultRule terakhir untuk dijalankan:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

Salah satu penggunaan DefaultFaultRule adalah menentukan jenis error yang terjadi jika Anda tidak dapat menentukannya. Misalnya, proxy API Anda gagal karena error yang tidak dapat Anda tentukan. Gunakan DefaultFaultRule untuk memanggil kebijakan ProvideMessage berikut. Kebijakan ini menulis nilai fault.name ke header bernama DefaultFaultHeader dalam respons:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Anda kemudian dapat melihat header di alat pelacakan Edge atau pada respons untuk melihat penyebab error.

Menambahkan logging pesan ke PostClientFlow

PostClientFlow adalah satu-satunya alur yang dijalankan setelah proxy memasuki status error. Hanya kebijakan MessageLogging yang dapat ditambahkan ke alur ini, yang dijalankan setelah respons dikirim kembali ke klien. Meskipun melampirkan kebijakan MessageLogging ke alur ini secara teknis bukanlah penanganan error, Anda dapat menggunakannya untuk mencatat informasi jika terjadi error. Karena proxy ini dijalankan terlepas dari apakah proxy berhasil atau gagal, Anda dapat menempatkan kebijakan Message Logging di PostClientFlow dan memastikan bahwa kebijakan tersebut selalu dijalankan.

Menangani kesalahan kebijakan dalam alur saat ini

Semua contoh yang ditampilkan sejauh ini menggunakan FaultRule pada ProxyEndpoint atau TargetEndpoint untuk menangani error kebijakan sebagai bagian dari status error. Hal ini karena nilai default elemen continueOnError kebijakan adalah false. Artinya, saat terjadi error dalam kebijakan, kontrol akan dialihkan ke status error. Setelah berada dalam status error, Anda tidak dapat mengembalikan kontrol ke pipeline normal dan Anda biasanya menampilkan beberapa bentuk pesan error ke aplikasi pemanggil.

Namun, jika Anda menyetel elemen continueOnError ke true untuk suatu kebijakan, kontrol akan tetap berada dalam alur saat ini dan kebijakan berikutnya dalam pipeline akan dijalankan setelah kebijakan yang menyebabkan error. Keuntungan menangani error dalam alur saat ini adalah Anda mungkin memiliki cara untuk pulih dari error guna menyelesaikan pemrosesan permintaan.

Di bawah ini adalah kebijakan VerifyAPIKey bernama verify-api-key dengan elemen continueOnError ditetapkan ke true:

<VerifyAPIKey async="false" continueOnError="true" enabled="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 akan berlanjut dalam alur saat ini.

Anda kemudian dapat 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 dalam PreFlow menggunakan kondisi untuk menguji adanya error. Jika terjadi error dalam kebijakan VerifAPIKey, kebijakan yang bernama kebijakan FaultInFlow akan dijalankan. Jika tidak, kebijakan FaultInFlow akan dilewati. Kebijakan FaultInFlow dapat melakukan banyak hal, seperti mencatat error, mencoba memperbaiki error, atau melakukan beberapa tindakan lainnya.

Memicu error menggunakan kebijakan RaiseFault

Anda dapat menggunakan kebijakan RaiseFault kapan saja dalam alur untuk memicu error. Saat dijalankan, kebijakan RaiseFault akan menghentikan flow 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 <Step> PreFlow yang menyebabkan kebijakan FaultInFlow dijalankan jika kondisi terpenuhi. Jika FaultInFlow adalah kebijakan RaiseFault, kontrol akan ditransfer ke status error. Atau, Anda dapat memasukkan kebijakan RaiseFault dalam flow 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}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

Perhatikan bahwa kondisi tersebut menguji kesalahan yang bernama RaiseFault. Kebijakan RaiseFault selalu menetapkan nilai fault.name ke RaiseFault.

Penanganan khusus kode error HTTP 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 di level transport, yang berarti error HTTP ditampilkan dari server target. Untuk mengontrol respons dari error HTTP, konfigurasikan TargetEndpoint untuk memproses kode respons HTTP.

Secara default, Edge memperlakukan kode respons HTTP dalam rentang 1xx-3xx sebagai 'berhasil', dan kode respons HTTP dalam rentang 4xx-5xx sebagai 'kegagalan'. Artinya, setiap respons dari layanan backend dengan kode respons HTTP 4xx-5xx akan otomatis memanggil status error, yang kemudian akan menampilkan pesan error langsung ke klien yang meminta.

Anda dapat membuat pengendali kustom untuk setiap kode respons HTTP. 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.

Pada contoh berikutnya, Anda menggunakan properti success.codes untuk mengonfigurasi TargetEndpoint agar memperlakukan kode respons HTTP 400 dan 500 sebagai sukses, bersama dengan kode HTTP default. Dengan memperlakukan kode tersebut sebagai berhasil, TargetEndpoint akan 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 terlihat dalam contoh ini, Anda dapat menggunakan karakter pengganti untuk menetapkan properti success.codes ke suatu rentang nilai.

Menetapkan properti success.codes akan menimpa nilai default. Oleh karena itu, jika Anda ingin menambahkan kode HTTP 400 ke daftar kode berhasil default, tetapkan properti ini sebagai:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Namun, jika Anda hanya ingin kode HTTP 400 yang diperlakukan sebagai kode berhasil, tetapkan properti sebagai:

<Property name="success.codes">400</Property>

Sekarang Anda dapat menentukan pengendali kustom untuk kode respons HTTP 400 dan 500 agar 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

Layanan API mengatur fault 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 secara eksplisit ditangani oleh proxy API menggunakan kebijakan RaiseFault
Kode respons InternalServerError, NotFound Kode kesalahan 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)
Transpor Error tingkat transport HTTP
Konektivitas ConnectionRefused, ConnectionReset, ConnectionTimeout Kegagalan terjadi saat membuat koneksi tingkat jaringan atau transport
Meminta validasi ContentLengthTidak Ada, 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, error TLS/SSL, dan error potongan
Sistem Error runtime yang tidak ditentukan
Memori OutOfMemory, GCOverLimit Kegagalan terkait memori
Rangkaian pesan RogueTaskTerminated Kegagalan seperti penghentian tugas run-away
Kebijakan Kesalahan untuk setiap jenis Kebijakan didefinisikan di Referensi Kebijakan.

Error selalu disertai dengan deskripsi teks tentang alasan kegagalan. Saat sistem melakukan kesalahan, serangkaian atribut akan diisi untuk membantu pemecahan masalah. Error mencakup informasi berikut:

  • Alasan
  • Atribut khusus buatan pengguna