Menangani error

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

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

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

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

Sebelum kita membahas penerapan penanganan error kustom di proxy API, sebaiknya Anda memahami cara error terjadi dan reaksi proxy API terhadapnya.

Video

Tonton video berikut untuk mempelajari lebih lanjut penanganan error.

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

Cara terjadinya error

Pertama, kita akan membahas cara error terjadi. Mengetahui cara terjadinya error akan membantu Anda merencanakan berbagai situasi tempat Anda ingin menerapkan penanganan error kustom.

Error otomatis

Proxy API akan menampilkan error secara otomatis dalam situasi berikut:

  • Kebijakan menampilkan 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 mengetahui jenis error yang dapat ditampilkan kebijakan).
  • Ada masalah dalam alur pesan proxy API, seperti error pemilihan rute.
  • Ada kegagalan backend, seperti error HTTP karena kegagalan tingkat protokol, error TLS/SSL, atau layanan target yang tidak tersedia.
  • Terjadi kegagalan tingkat sistem, seperti pengecualian kehabisan memori.

Untuk informasi selengkapnya tentang error ini, lihat Taksonomi error dalam topik ini.

Error kustom

Untuk situasi saat 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 yang Anda lakukan pada kebijakan lainnya. Dalam contoh konfigurasi proxy berikut, kebijakan Raise-Fault-1 dilampirkan ke respons TargetEndpoint. Jika kata unavailable ada dalam respons dari layanan target, kebijakan RaiseFault akan dijalankan dan menampilkan error.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>message.content Like "*unavailable*"</Condition>
    </Step>
  </Response>

Ini hanya untuk menunjukkan bahwa Anda dapat menampilkan error kustom. Kami membahas kebijakan RaiseFault secara lebih mendetail di bagian FaultRules vs. kebijakan RaiseFault.

Untuk contoh lainnya, lihat postingan Komunitas Apigee berikut:

Tindakan proxy API saat terjadi error

Berikut adalah hal yang terjadi saat proxy menampilkan error.

Keluar dari pipeline proxy

Saat proxy API mengalami error, terlepas dari bagaimana error tersebut terjadi, proxy akan keluar dari pipeline alur normal, memasuki status error, dan menampilkan pesan error ke aplikasi klien. Setelah proxy API memasuki status error, proxy tidak dapat mengembalikan pemrosesan kembali ke pipeline alur normal.

Misalnya, asumsikan proxy API memiliki kebijakan dalam urutan berikut dalam permintaan ProxyEndpoint:

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

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

Memeriksa FaultRules

Dalam status error, proxy API juga memeriksa keberadaan hal berikut (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 ada yang dieksekusi.
    • Elemen <AlwaysEnforce> disetel ke benar (true).

Pada dasarnya, proxy API memberi Anda kesempatan untuk menampilkan pesan error kustom dan memicu logika lainnya. Jika proxy tidak menemukan salah satu bagian tersebut, atau ada, tetapi tidak ada error kustom yang dipicu, proxy akan mengirim pesan default buatan Apigee-nya sendiri.

Contoh penanganan error sederhana

Mari kita mulai dengan contoh sederhana, yaitu 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 mengetahui pesan error, tetapi mungkin juga tidak. Selain itu, banyak error default yang lebih halus dan lebih sulit diuraikan.

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 maupun grup pengujian internal yang memiliki persyaratan format pesan errornya sendiri.

Berikut adalah contoh dasar cara membuat pesan error kustom untuk menangani error ini. Hal ini memerlukan 1) kebijakan yang menentukan pesan kustom, dan 2) FaultRule yang mengeksekusi kebijakan saat proxy beralih ke status error.

1. Buat kebijakan yang menentukan pesan kustom

Pertama, buat kebijakan yang menentukan pesan error kustom. Anda dapat menggunakan jenis kebijakan apa pun, seperti kebijakan AssignMessage, yang dapat menetapkan payload dan header HTTP opsional seperti kode status dan frasa alasan. Kebijakan AssignMessage sangat cocok untuk hal ini. Dengan begitu, Anda dapat mengontrol payload pesan, menetapkan kode status HTTP yang berbeda, menetapkan frasa alasan HTTP yang berbeda, dan menambahkan header HTTP.

Anda tidak perlu melampirkan kebijakan ke alur; cukup buat, seperti yang dijelaskan dalam Membuat kebijakan.

Berikut adalah contoh kebijakan AssignMessage yang:

  • Menampilkan pesan JSON.
  • Menetapkan kode status HTTP (911, yang merupakan kode status yang jelas tidak ada hanya untuk mengilustrasikan fleksibilitas yang Anda miliki). Kode status muncul di header HTTP.
  • Menetapkan frasa alasan HTTP (untuk mengganti frasa alasan Unauthorized default untuk error kunci API yang hilang ini). Frasa alasan muncul di samping kode status di header HTTP.
  • Membuat dan mengisi header HTTP baru yang disebut 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>
    </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 ke aplikasi klien akan terlihat seperti berikut. Bandingkan dengan respons default yang ditampilkan 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 memang sedikit konyol, tetapi menunjukkan kepada Anda apa yang mungkin dilakukan. Setidaknya sekarang developer yang menerima pesan tersebut tahu bahwa ia lupa menyertakan kunci API sebagai parameter kueri.

Namun, bagaimana kebijakan ini dieksekusi? 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>. Setiap FaultRule mewakili error yang 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 yang dieksekusi.

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. Hal ini penting. Selengkapnya tentang cara menempatkan FaultRules di ProxyEndpoint vs. TargetEndpoint nanti.
  • <Name>: Nama kebijakan yang akan dieksekusi. Nama ini berasal dari atribut name kebijakan pada elemen induk, seperti yang ditunjukkan dalam contoh kebijakan sebelumnya.

  • <Condition>: Apigee mengevaluasi kondisi dan menjalankan kebijakan hanya jika kondisinya benar. Jika ada beberapa FaultRules yang dievaluasi ke benar, Apigee akan menjalankan FaultRules pertama yang benar. (Penting: Urutan evaluasi FaultRules, 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 kondisi, FaultRule akan otomatis bernilai benar. Namun, itu bukan praktik terbaik. Setiap FaultRule harus memiliki kondisinya sendiri.

  • <DefaultFaultRule>: Jika tidak ada FaultRule kustom yang dijalankan, <DefaultFaultRule> akan dijalankan, yang mengirimkan pesan kustom yang lebih umum, bukan pesan default yang dibuat Apigee yang samar. <DefaultFaultRule> juga dapat memiliki <Condition>, tetapi dalam sebagian besar kasus, Anda tidak akan menyertakannya, karena Anda ingin <Condition> dieksekusi apa pun 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 mudah digunakan developer sekaligus mengaburkan URL backend atau informasi lain yang mungkin digunakan untuk membahayakan sistem.

Beberapa FaultRules dan logika eksekusi

Di bagian Contoh penanganan error sederhana, kita menggunakan contoh sederhana satu FaultRule dan kondisi. Dalam project API di dunia nyata, dengan semua kemungkinan error yang dapat terjadi, Anda mungkin memiliki beberapa FaultRules dan DefaultFaultRule di <ProxyEndpoint> dan <TargetEndpoint>. Namun, pada akhirnya, hanya satu FaultRule yang dieksekusi saat proxy API berstatus error.

Bagian ini menjelaskan logika yang digunakan Apigee dalam menangani FaultRules, mulai dari cara FaultRules tunggal dijalankan hingga cara kondisi Langkah dalam ditangani saat FaultRule-nya dipicu. Bagian ini juga memberikan panduan tentang kapan harus menentukan FaultRules di <ProxyEndpoint> vs. <TargetEndpoint>, dan menjelaskan hubungan antara FaultRules dan kebijakan RaiseFault.

Eksekusi FaultRules

Singkatnya, berikut adalah logika yang digunakan Apigee saat proxy API mengalami status error. Perhatikan bahwa ada sedikit perbedaan antara evaluasi FaultRules di ProxyEndpoint versus TargetEndpoint.

  1. Apigee mengevaluasi FaultRules di ProxyEndpoint atau TargetEndpoint, bergantung pada tempat terjadinya error:
    • ProxyEndpoint - Apigee dimulai dengan <FaultRule> bawah dalam XML konfigurasi dan terus naik, mengevaluasi <Condition> dari setiap <FaultRule> (kondisi luar, bukan kondisi <Step> dalam).
    • TargetEndpoint - Apigee dimulai dengan <FaultRule> atas dalam XML konfigurasi dan terus ke bawah, mengevaluasi <Condition> dari setiap <FaultRule> (kondisi luar, bukan kondisi <Step> dalam).
  2. Menjalankan FaultRule pertama yang kondisinya benar. Jika tidak memiliki kondisi, FaultRule akan bernilai benar secara default.
    • Saat FaultRule dieksekusi, semua Langkah di dalam FaultRule dievaluasi secara berurutan, dari atas ke bawah dalam konfigurasi XML. Langkah tanpa kondisi akan otomatis dijalankan (kebijakan dijalankan), dan Langkah yang memiliki <Condition> yang dievaluasi akan dijalankan (kondisi yang dievaluasi menjadi code tidak dijalankan).

    • Jika FaultRule dieksekusi, tetapi tidak ada langkah dalam FaultRule yang dieksekusi (karena kondisinya bernilai code), pesan error default yang dihasilkan Apigee akan ditampilkan ke aplikasi klien. <DefaultFaultRule> tidak dieksekusi, karena Apigee telah mengeksekusi satu FaultRule-nya.

  3. Jika tidak ada FaultRule yang dieksekusi, Apigee akan mengeksekusi <DefaultFaultRule>, jika ada.

Berikut adalah contoh dengan komentar inline.

Eksekusi ProxyEndpoint

Evaluasi ProxyEndpoint FaultRules adalah dari bawah ke atas, jadi mulailah membaca dari 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), Apigee
     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, Apigee looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Apigee 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 Apigee has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Eksekusi TargetEndpoint

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

Urutan aturan error

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

Contoh:

Urutan ProxyEndpoint Urutan TargetEndpoint

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

5. FaultRule 1: SALAH

4. FaultRule 2: TRUE

3. FaultRule 3: TRUE

2. FaultRule 4: SALAH

1. FaultRule 5: SALAH

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

1. FaultRule 1: SALAH

2. FaultRule 2: TRUE

3. FaultRule 3: TRUE

4. FaultRule 4: SALAH

5. FaultRule 5: SALAH

Kebijakan yang akan disertakan

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

Aturan error HANYA dipicu dalam status error (tentang continueOnError)

Judul ini mungkin tampak seperti kita mengulangi, tetapi ada satu nuansa khusus yang harus diperhatikan terkait error proxy yang menyebabkan proxy API memasuki status error—atau tidak memasuki status error: atribut continueOnError pada kebijakan.

Untuk merangkum: Proxy API mengevaluasi <FaultRules> dan <DefaultFaultRule> hanya jika proxy telah memasuki status error. Artinya, walaupun kondisi FaultRule bernilai benar, 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 sehubungan dengan penanganan error, karena menentukan apakah proxy masuk ke status error atau tidak jika kebijakan gagal. Dalam sebagian besar kasus, Anda sebaiknya 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 Service Callout menghentikan eksekusi proxy), proxy tidak akan berstatus error jika kebijakan tersebut gagal, dan proxy tidak akan melihat FaultRules Anda.

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

Tempat menentukan FaultRules: ProxyEndpoint atau TargetEndpoint

Saat proxy API mengalami error, error tersebut terjadi di <ProxyEndpoint> (permintaan dari atau respons ke aplikasi klien) atau di <TargetEndpoint> (permintaan ke atau respons dari layanan target). Di mana saja error tersebut terjadi, Apigee akan mencari FaultRules.

Misalnya, jika server target tidak tersedia (kode status HTTP 503), proxy API akan masuk ke status error dalam respons <TargetEndpoint>, dan alur proxy API normal tidak akan dilanjutkan ke <ProxyEndpoint>. Jika Anda memiliki FaultRules yang ditentukan hanya di <ProxyEndpoint>, FaultRules tersebut tidak akan menangani error tersebut.

Berikut contoh lainnya. Jika kebijakan RaiseFault pada respons <ProxyEndpoint> memicu error, FaultRule di <TargetEndpoint> tidak akan dieksekusi.

FaultRules vs. kebijakan RaiseFault

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

Singkatnya:

  • Aturan error selalu dievaluasi saat proxy API memasuki status error.

  • Kebijakan RaiseFault adalah cara untuk menempatkan proxy API dalam status error jika error tidak akan terjadi.

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

Apa yang terjadi jika kebijakan RaiseFault memicu error, yang menempatkan proxy dalam status error, yang berpotensi mengeksekusi FaultRule? Di sinilah hal-hal bisa menjadi sedikit rumit. Jika kebijakan RaiseFault menampilkan pesan error dan FaultRule dipicu dan menampilkan pesan error, apa yang ditampilkan ke aplikasi klien?

  • Karena FaultRule atau DefaultFaultRule dijalankan setelah kebijakan RaiseFault, data respons FaultRule akan lebih diutamakan.
  • Data respons kebijakan RaiseFault (kode status, frasa alasan, atau payload pesan) digunakan jika data tersebut tidak ditetapkan oleh FaultRule atau DefaultFaultRule.
  • Jika kebijakan RaiseFault dan FaultRule menambahkan header HTTP kustom, keduanya akan disertakan dalam respons. Nama header duplikat akan membuat header dengan beberapa nilai.

Berikut adalah contoh yang ditetapkan oleh kebijakan RaiseFault dan FaultRule, serta yang ditampilkan ke aplikasi klien. Contoh ini dirancang untuk ringkas, bukan untuk praktik terbaik.

Yang ditetapkan oleh kebijakan RaiseFault dan FaultRule.

Aplikasi klien menerima:

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

<- Kebijakan aturan error menetapkan ini:

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

<- Kebijakan RaiseFault menetapkan ini:

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

Mem-build kondisi

Kondisi adalah kunci untuk eksekusi FaultRule. Anda membuat kondisi FaultRule dengan cara yang sama seperti yang Anda lakukan untuk kondisi lain di Apigee, seperti untuk alur bersyarat atau kondisi RaiseFault.

Untuk menempatkan bagian lain dari bagian ini dalam konteks, berikut adalah contoh aturan error yang memiliki kondisi FaultRule luar dan kondisi Step 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 contoh berikut, nama error adalah FailedToResolveAPIKey. Dalam hal ini, variabel alur 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 mengetahui daftar error kebijakan.

{policy_namespace}.{policy_name}.failed

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

Saat 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 titik kegagalan. Misalnya, jika error ditampilkan dalam respons, FaultRule di <TargetEndpoint> dapat menggunakan data HTTP response.status.code, message.content, error.content, dan sebagainya. Atau, jika kebijakan Kuota gagal, Anda dapat menggunakan variabel ratelimit.{quota_policy_name}.exceed.count. Gunakan Alat debug dan Referensi kebijakan untuk membantu Anda mengetahui variabel dan data HTTP yang tersedia.

Informasi selengkapnya

Praktik terbaik untuk penanganan error

Penanganan error adalah tugas desain arsitektur utama untuk pengembangan proxy API. Sebaiknya luangkan waktu untuk mencari tahu cara dan waktu Anda akan menangani error, menentukan pesan error yang akan ditampilkan, dan mendesain format pesan error. Setelah (atau saat) Anda mengetahui hal-hal tersebut, gunakan praktik terbaik ini untuk membantu Anda dalam penerapan penanganan error.

Berikut adalah beberapa praktik terbaik dalam mendesain dan mem-build penanganan error:

  • Di FaultRules, Anda dapat menentukan jenis kebijakan apa pun. Pola yang paling umum adalah menggunakan kebijakan AssignMessage untuk menetapkan item tertentu dalam respons error yang tertunda. Anda juga dapat menggunakan AssignMessage untuk menetapkan variabel yang digunakan untuk tujuan lain, misalnya, untuk variabel yang dirujuk oleh kebijakan logging yang dieksekusi di PostClientFlow, atau di FlowHooks. Pertimbangkan juga untuk mencatat pesan ke dalam log, misalnya dengan kebijakan MessageLogging atau kebijakan ServiceCallout, jika Anda ingin mencatat error tertentu dalam kondisi error tertentu.
  • Jangan tentukan kebijakan RaiseFault sebagai Langkah dalam FaultRule. Sebaiknya gunakan kebijakan AssignMessage untuk menetapkan atau mengubah elemen pesan, termasuk payload, header, atau kode status.
  • Untuk setiap FaultRule, atau untuk semua kecuali FaultRule yang dievaluasi terakhir, berikan <Condition> luar yang dilampirkan sebagai turunan dari elemen <FaultRule>. Kondisi eksekusi untuk FaultRule tanpa Kondisi eksplisit yang ditentukan, akan dievaluasi secara implisit menjadi true. Elemen <Condition> yang dilampirkan sebagai turunan elemen <Step> tidak digunakan untuk menentukan apakah kondisi eksekusi untuk FaultRule bernilai true atau false. Kondisi langkah hanya dievaluasi setelah Apigee mengeksekusi FaultRule yang berisinya. Dalam FaultRule, biasanya ada beberapa Langkah dengan kebijakan AssignMessage (atau lainnya), masing-masing dengan kondisi Langkah.

  • Untuk menangani error dalam beberapa kebijakan dari jenis yang sama (misalnya, beberapa kebijakan Quota), buat satu FaultRule per error kebijakan yang kemungkinan akan Anda terima, lalu bedakan antara error terpisah dengan Kondisi yang dilampirkan ke Langkah. Misalnya, buat FaultRule untuk menangani error dalam kebijakan Kuota, seperti QuotaViolation, dan FaultRule terpisah untuk InvalidApiKey. (Lihat Referensi error kebijakan untuk error kebijakan. Saat menemukan error tambahan yang perlu ditangani, Anda dapat kembali nanti dan menambahkannya ke FaultRules. Tidak masalah jika bersifat iteratif, meskipun memerlukan deployment ulang proxy.) Pendekatan ini memungkinkan Anda menangkap jenis error yang sama, apa pun kebijakan yang menampilkannya, sehingga XML FaultRules Anda menjadi efisien.

    Kondisi Langkah dalam memberi Anda kontrol yang lebih terperinci. Misalnya, jika Anda menerapkan kuota developer individual dan kuota global dengan dua kebijakan dalam alur permintaan, tetapkan kondisi FaultRule outer untuk dipicu pada error QuotaViolation (yang ditampilkan saat kuota melebihi batas dalam kedua kasus). Kemudian, tetapkan kondisi Langkah untuk mengevaluasi variabel exceed.count tertentu di kedua kebijakan kuota Anda. Hanya error yang relevan yang 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>AM-developer-over-quota-fault</Name>
    <Condition>ratelimit.developer-quota-policy.exceed.count GreaterThan 0</Condition>
  </Step>
  <Step>
    <Name>AM-global-over-quota-fault</Name>
    <Condition>ratelimit.global-quota-policy.exceed.count GreaterThan 0</Condition>
  </Step>
</FaultRule>

    Untuk contoh lain, lihat diskusi tentang Penanganan error kebijakan ini.

  • Untuk menangani error saat Anda menggunakan satu kebijakan dari satu jenis, pertimbangkan satu aturan error yang dijalankan saat satu kebijakan tersebut gagal, dan sertakan beberapa langkah yang dipetakan ke setiap kemungkinan error. Hal ini membuat XML Anda lebih sederhana dengan menggunakan satu FaultRule, bukan beberapa FaultRule (satu untuk setiap jenis error). Misalnya, Anda dapat menentukan bahwa langkah-langkah kebijakan AssignMessage yang berbeda dijalankan dalam kondisi yang berbeda, seperti ini:

    <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>AM-Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>AM-API-Key-NotFound</Name>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
  </Step>
  <Step>
    <Name>AM-API-Key-Invalid</Name>
    <Condition>fault.name = "InvalidApiKey"</Condition>
  </Step>
</FaultRule>
  • Tambahkan FaultRules tempat error akan terjadi (<ProxyEndpoint> sisi klien atau <TargetEndpoint> sisi target). Sertakan FaultRules untuk setiap kebijakan yang muncul di setiap lokasi.
  • Saat menggunakan kebijakan RaiseFault bersama dengan FaultRules, koordinasikan data respons yang dikirim kembali saat kebijakan RaiseFault dan FaultRule menampilkan data. Misalnya, jika Anda memiliki kebijakan RaiseFault yang menetapkan kode status HTTP, jangan juga mengonfigurasi AssignMessage Step dalam FaultRule yang mereset kode status. Hal terburuk yang dapat terjadi adalah kode status default ditampilkan ke aplikasi klien.

  • Elemen <DefaultFaultRule> melengkapi elemen <FaultRules> untuk memberi Anda kontrol lebih besar atas kebijakan yang dijalankan proxy saat menangani status error. Jika Anda menentukan <DefaultFaultRule>, <DefaultFaultRule> akan dieksekusi jika salah satu atau kedua hal berikut terpenuhi:

    • Tidak ada FaultRule lain yang dieksekusi. Kasus khusus di sini adalah jika tidak ada elemen <FaultRules> yang dikonfigurasi sama sekali.
    • Jika elemen turunan <AlwaysEnforce> dari <DefaultFaultRule> bernilai benar.

    Anda juga dapat menentukan elemen <Condition> pada <DefaultFaultRule>. Anda mungkin ingin melakukannya untuk mengecualikan eksekusinya berdasarkan beberapa status permintaan atau pesan error yang tertunda, misalnya jika header tertentu ada atau tidak ada.

    Gunakan <DefaultFaultRule> dengan <AlwaysEnforce> disetel ke true, jika Anda memiliki satu atau beberapa kebijakan yang ingin selalu dijalankan oleh proxy, terlepas dari apakah FaultRule sebelumnya telah dieksekusi. Salah satu kemungkinan skenario: misalnya Anda ingin memasukkan header ke dalam respons dalam semua kasus, baik permintaan proxy menghasilkan error maupun tidak, dan apakah error tersebut telah ditangani sebelumnya atau tidak. Kemudian, Anda akan melampirkan kebijakan AssignMessage yang sesuai di bagian <PostFlow>/<Response>, dan juga melampirkan kebijakan yang sama di <DefaultFaultRule> dengan <AlwaysEnforce> ditetapkan ke true.

Pola untuk penanganan error terpusat yang dapat digunakan kembali

Pola penanganan error untuk proxy Apigee menjelaskan pola untuk penanganan error terpusat tanpa duplikasi kode.

Membuat FaultRules

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

Jika Anda membuat FaultRules di UI Apigee, buat kebijakan yang ingin dieksekusi 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 Anda dapat menempatkan kebijakan apa pun di FaultRule, Anda biasanya menggunakan kebijakan AssignMessage untuk membuat pesan respons kustom untuk kondisi error. AssignMessage memungkinkan Anda mengonfigurasi respons HTTP dengan elemen payload, kode status HTTP, header, dan frasa alasan.

Contoh di bawah menunjukkan konfigurasi kebijakan AssignMessage standar:

<AssignMessage name="AM-Invalid-Key">
  <Set>
      <Payload contentType="text/plain">That is an error.</Payload>
      <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Perhatikan bahwa kode ini tidak menentukan elemen <AssignTo>. Artinya, kebijakan akan ditetapkan ke pesan standby, bergantung pada tempat kebijakan dilampirkan.

Sekarang Anda dapat menggunakan kebijakan ini di FaultRule. Perhatikan cara Anda mereferensikan kebijakan AssignMessage berdasarkan nama di FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

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

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

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

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

  • Setiap kebijakan di FaultRule menyebabkan error
  • Setiap 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. Dengan begitu, Anda memberikan informasi yang konsisten dan bermanfaat kepada klien.

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

<AssignMessage name="AM-Invalid-Key">
  <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>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Respons ini menyertakan:

  • 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 apa pun yang tidak ditangani secara eksplisit oleh FaultRule lain. Jika kondisi untuk semua FaultRules tidak cocok dengan error, DefaultFaultRule akan menangani error tersebut. Aktifkan penanganan error default dengan menambahkan tag <DefaultFaultRule> sebagai elemen turunan ProxyEndpoint atau TargetEndpoint.

Misalnya, konfigurasi TargetEndpoint di bawah menentukan DefaultFaultRule yang memanggil kebijakan bernama AM-Return-Generic-Error:

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

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>https://mytarget.example.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 mudah dipahami developer sekaligus mengaburkan URL backend atau informasi lain yang mungkin digunakan untuk membahayakan sistem.

Misalnya, Anda menentukan kebijakan AssignMessage berikut untuk menampilkan error umum:

<AssignMessage name="AM-Return-Generic-Error">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

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

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

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

<AssignMessage name="AM-Set-Fault-Header">
  <Set>
    <Headers>
      <Header name="Unhandled-Fault">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Kemudian, Anda dapat melihat header di Alat debug atau pada respons untuk melihat penyebab error.

Menambahkan logging pesan ke PostClientFlow

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

Menangani error kebijakan dalam alur saat ini

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

Namun, jika Anda menetapkan elemen continueOnError ke true untuk 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 memulihkan dari error untuk menyelesaikan pemrosesan permintaan.

Yang ditampilkan di bawah adalah kebijakan VerifyAPIKey bernama verify-api-key dengan elemen continueOnError ditetapkan ke true:

<VerifyAPIKey continueOnError="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.

Kemudian, tambahkan 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 di PreFlow menggunakan kondisi untuk menguji keberadaan error. Jika terjadi error dalam kebijakan VerifyAPIKey, kebijakan bernama FaultInFlow akan dijalankan. Jika tidak, kebijakan FaultInFlow akan dilewati. Kebijakan FaultInFlow dapat melakukan banyak hal, seperti mencatat error ke dalam log, 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 alur 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> Pra-Aliran yang menyebabkan kebijakan FaultInFlow dijalankan jika kondisi terpenuhi. Jika FaultInFlow adalah kebijakan RaiseFault, kontrol akan ditransfer ke status error. Atau, Anda dapat menyisipkan kebijakan RaiseFault dalam alur untuk men-debug dan menguji FaultRules.

Saat kebijakan RaiseFault memicu error, Anda dapat menggunakan FaultRule dan kondisi berikut untuk memprosesnya:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>POLICY-NAME-HERE</Name>
  </Step>
  <Condition>fault.name = "RaiseFault"</Condition>
</FaultRule>

Perhatikan bahwa kondisi menguji kesalahan bernama RaiseFault. Kebijakan RaiseFault selalu menetapkan nilai fault.name ke RaiseFault. Anda juga dapat menetapkan variabel kustom dalam kebijakan RaiseFault. Jika melakukannya, Anda dapat menguji variabel tersebut dalam elemen Kondisi.

Penanganan kustom 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 tingkat transpor, yang berarti error HTTP yang ditampilkan dari server target. Untuk mengontrol respons dari error HTTP, konfigurasikan TargetEndpoint untuk memproses kode respons HTTP.

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

Anda dapat membuat pengendali kustom untuk kode respons HTTP apa pun. 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 berhasil, 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 dapat Anda lihat dalam contoh ini, Anda dapat menggunakan karakter pengganti untuk menetapkan properti success.codes ke rentang nilai.

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

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

Namun, jika Anda hanya ingin kode HTTP 400 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 untuk 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 error

Layanan API mengatur error ke dalam kategori dan subkategori berikut.

Kategori Subkategori Nama Gangguan Deskripsi
Pesan Kegagalan yang terjadi selama alur pesan (tidak termasuk kegagalan kebijakan)
Error kustom {fault_name} Setiap error yang ditangani secara eksplisit oleh proxy API menggunakan kebijakan RaiseFault
Kode respons InternalServerError, NotFound Kode error HTTP 5xx, 4xx
Kegagalan perutean NoRoutesMatched Kegagalan dalam 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)
Transportasi Error tingkat transpor HTTP
Konektivitas ConnectionRefused, ConnectionReset, ConnectionTimeout Kegagalan terjadi saat membuat koneksi tingkat jaringan atau transpor
Meminta validasi ContentLengthMissing, HostHeaderMissing Error terjadi selama pemeriksaan semantik pada setiap permintaan
Validasi respons Error 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 habis, error TLS/SSL, dan error yang dikelompokkan
Sistem Error runtime yang tidak ditentukan
Memori OutOfMemory, GCOverLimit Kegagalan terkait memori
Rangkaian pesan RogueTaskTerminated Kegagalan seperti penghentian tugas yang berjalan tanpa henti
Kebijakan Error untuk setiap jenis kebijakan ditentukan dalam Referensi kebijakan.

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

  • Alasan
  • Atribut kustom yang ditentukan pengguna