Menangani kesalahan

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

Banyak kondisi error dapat muncul saat proxy API melayani permintaan dari aplikasi. Sebagai contoh, proxy API mungkin mengalami masalah jaringan saat berkomunikasi dengan layanan backend, aplikasi mungkin menunjukkan kredensial yang sudah tidak berlaku, pesan permintaan mungkin tidak diformat dengan benar, kueri.

Ketika kesalahan terjadi setelah aplikasi klien memanggil proxy API, pesan kesalahan akan dikembalikan ke klien. Secara {i>default<i}, klien sering menerima pesan {i>error<i} yang samar tanpa detail atau panduan. Tetapi jika Anda ingin mengganti pesan {i>error<i} {i>default<i} dengan pesan khusus yang lebih berguna, dan bahkan memperkayanya dengan hal-hal seperti header HTTP tambahan, Anda perlu menyiapkan kesalahan dan ditangani di Edge.

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

Sebelum kita membahas tentang penerapan penanganan error kustom di proxy API Anda, sebaiknya memahami bagaimana error terjadi dan bagaimana proxy API bereaksi terhadapnya.

Video

Tonton video berikut untuk mempelajari lebih lanjut penanganan kesalahan.

Bagaimana kesalahan terjadi

Pertama-tama, kita akan membahas bagaimana error terjadi. Mengetahui bagaimana kesalahan terjadi membantu Anda merencanakan untuk berbagai situasi di mana Anda ingin menerapkan penanganan error kustom.

Error otomatis

Proxy API menampilkan error secara otomatis dalam situasi berikut:

• Kebijakan akan menampilkan error. Misalnya, jika panggilan API mengirimkan kunci yang sudah tidak berlaku, Kebijakan VerifyAPIKey otomatis menampilkan error; atau jika jumlah panggilan API melampaui batas tertentu, Kebijakan kuota atau kebijakan SpikeArrest akan menampilkan error. (Lihat Referensi error kebijakan untuk mengetahui jenis kebijakan error yang dapat ditampilkan).
• Ada masalah dalam alur pesan proxy API, misalnya error pemilihan rute.
• Terjadi kegagalan backend, seperti error HTTP karena kegagalan tingkat protokol, TLS/SSL error, atau layanan target tidak tersedia.
• Terjadi kegagalan tingkat sistem, misalnya pengecualian kehabisan memori.

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

Error kustom

Jika tidak ada error otomatis, Anda mungkin perlu menampilkan error kustom; untuk misalnya, jika respons berisi kata "unavailable", atau jika kode status HTTP lebih dari 201. Lakukan ini dengan menambahkan kebijakan RaiseFault ke di tempat yang sesuai dalam alur proxy API.

Anda dapat menambahkan kebijakan RaiseFault ke alur proxy API dengan cara yang sama seperti yang Anda lakukan pada kebijakan lainnya. Di beberapa contoh konfigurasi proxy berikut, kebijakan Raise-Fault-1 terpasang pada respons TargetEndpoint. Jika kata "tidak tersedia" ada dalam respons dari target layanan, kebijakan RaiseFault dijalankan dan menampilkan pesan {i>error<i}.

<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. Kita akan membahas Kebijakan RaiseFault dalam kebijakan FaultRules vs. the RaiseFault bagian.

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

• Mereferensikan variabel JavaScript di RaiseFault

Tindakan proxy API saat terjadi error

Inilah yang terjadi ketika {i>proxy<i} menampilkan {i>error<i}.

Keluar dari pipeline proxy

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

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

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

Jika terjadi error selama verifikasi kunci API, proxy API akan beralih ke status error. Tujuan Kebijakan kuota dan JSON ke XML tidak dijalankan, proxy tidak dilanjutkan ke TargetEndpoint, dan pesan {i>error<i} dikembalikan ke aplikasi klien.

Memeriksa FaultRules

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

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

Intinya, proxy API memberi Anda kesempatan untuk menampilkan pesan kesalahan khusus dan memicu logika lainnya. Jika {i>proxy<i} menemukan tak satu pun dari bagian tersebut, atau bagian itu ada tetapi tidak ada khusus kesalahan dipicu, proxy mengirimkan pesan default yang dihasilkan Edge.

Contoh penanganan fault yang sederhana

Mari kita mulai dengan contoh sederhana, saat panggilan ke proxy API tidak berisi API yang diperlukan tombol. 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 tidak. Dan banyak yang default kesalahan terlihat halus dan lebih sulit untuk dipecahkan.

Sebagai pengembang API, terserah Anda untuk mengubah pesan ini untuk memenuhi kebutuhan siapa pun yang mau pada akhirnya menerima pesan error, baik itu developer aplikasi iOS atau pengujian internal yang memiliki persyaratan format pesan {i>error<i} sendiri.

Berikut adalah contoh dasar cara membuat pesan error kustom untuk menangani error ini. Ini memerlukan 1) kebijakan yang menentukan pesan kustom, dan 2) FaultRule yang menjalankan 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 semua jenis kebijakan, seperti kebijakan TetapkanMessage, yang dapat menetapkan payload dan header HTTP opsional seperti kode status dan frasa alasan. Opsi Tugaskan Pesan cocok untuk hal ini. Hal ini memungkinkan Anda untuk mengontrol {i>payload<i} pesan, mengatur kode status HTTP yang berbeda, menetapkan frasa alasan HTTP yang berbeda, dan menambahkan {i>header<i} HTTP.

Jangan lampirkan kebijakan ke alur apa pun di proxy API. Cukup saja data itu ada di dalam paket proxy. Untuk melakukannya di editor proxy UI pengelolaan, buka tab Pengembangan, dan Panel navigasi dan klik ikon + di panel Kebijakan.

Dengan begitu, Anda dapat membuat kebijakan tanpa melampirkannya ke alur di proxy API. Kebijakan yang tidak melekat pada alur apa pun ditandai dengan di daftar Kebijakan, seperti yang ditampilkan berdekatan dengan kebijakan pesan kunci API yang ditampilkan di gambar sebelumnya.

Berikut adalah contoh kebijakan MenetapkanMessage 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 permintaan ini kunci API tidak ada). Frasa alasan muncul di samping kode status di HTTP {i>header<i}.
• 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>

Jika kebijakan ini dijalankan, respons terhadap aplikasi klien akan terlihat seperti berikut. Bandingkan dengan respons {i>default<i} 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, terdengar konyol, tetapi ini menunjukkan kepada Anda apa yang mungkin dilakukan. Setidaknya sekarang developer menerima pesan tersebut tahu bahwa mereka lupa menyertakan kunci API sebagai parameter kueri.

Namun, bagaimana cara kebijakan ini dijalankan? Bagian berikutnya akan menunjukkan kepada Anda.

2. Buat &lt;FaultRule&gt; yang akan memicu kebijakan

Di bagian <ProxyEndpoint> atau <TargetEndpoint> konfigurasi proxy, Anda akan menambahkan blok XML <FaultRules> yang berisi satu atau lebih bagian <FaultRule> individual. Setiap FaultRule mewakili yang ingin Anda tangani. Dalam contoh sederhana ini, kami hanya akan menggunakan satu {i>FaultRule<i} untuk menunjukkan yang menyusunnya.

Anda juga harus menambahkan <DefaultFaultRule> untuk menampilkan error umum kustom jika tidak ada FaultRules 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. Selengkapnya tentang menempatkan FaultRules di ProxyEndpoint vs. TargetEndpoint nanti.
• <Name> - Nama kebijakan yang akan dieksekusi. Nama berasal dari atribut name kebijakan pada elemen induk, seperti yang ditunjukkan dalam contoh kebijakan sebelumnya.

• <Condition> - Edge mengevaluasi kondisi dan mengeksekusi kebijakan hanya jika kondisinya benar. Jika ada beberapa {i>FaultRules<i} yang bernilai benar, Edge mengeksekusi yang pertama benar. (Penting: urutan evaluasi FaultRules, dari atas ke bawah atau dari bawah ke atas, berbeda antara TargetEndpoint dan ProxyEndpoint, seperti yang dijelaskan dalam FaultRules dan execution logic.) Jika Anda tidak menyertakan kondisi, FaultRule secara otomatis nilainya adalah benar (true). Tapi itu bukan praktik terbaik. Setiap FaultRule harus memiliki .

• <DefaultFaultRule> - Jika tidak ada FaultRule kustom dieksekusi, <DefaultFaultRule> akan dieksekusi, mengirimkan model pesan khusus, alih-alih pesan default samar yang dibuat Edge. J <DefaultFaultRule> juga dapat memiliki <Condition>, tetapi di dalam kebanyakan kasus, Anda tidak akan menyertakannya, karena Anda ingin perintah itu dijalankan, tidak peduli apa yang resor.

  DefaultFaultRule biasanya digunakan untuk menampilkan pesan error umum untuk dan terjadi error tak terduga. Contohnya adalah pesan yang berisi informasi kontak untuk dukungan teknis. Respons {i>default<i} ini memiliki tujuan ganda untuk memberikan informasi yang mudah diterapkan dan juga mengaburkan URL backend atau informasi lain yang dapat digunakan untuk menyusupi sistem.

Beberapa FaultRules dan logika eksekusi

Di bagian Contoh penanganan kesalahan sederhana, kami menggunakan contoh sederhana dari satu FaultRule dan kondisi. Dalam project API dunia nyata, dengan semua kemungkinan error yang mungkin terjadi, kemungkinan Anda memiliki beberapa FaultRules dan DefaultFaultRule <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, dari cara Edge tiba di FaultRule tunggal untuk menjalankan ke “inner” (bagaimana) Kondisi langkah ditangani saat FaultRule-nya dipicu. Bagian ini juga memberikan panduan tentang kapan harus menentukan FaultRules dalam <ProxyEndpoint> vs. <TargetEndpoint>, dan menjelaskan hubungan antara FaultRules dan kebijakan RaiseFault.

Eksekusi FaultRules

Singkatnya, inilah logika yang digunakan Edge saat proxy API mengalami status error. Perlu diketahui bahwa ada sedikit perbedaan antara evaluasi FaultRules di ProxyEndpoint dan TargetEndpoint.

1. Edge mengevaluasi FaultRules di ProxyEndpoint atau TargetEndpoint, bergantung pada tempat error terjadi:
   • ProxyEndpoint - Edge dimulai dengan bagian bawah <FaultRule> dalam XML konfigurasi dan berjalan, mengevaluasi <Condition> dari setiap <FaultRule> ("outer" kondisi, bukan "bagian dalam" kondisi <Step>).
   • TargetEndpoint - Edge dimulai dengan bagian atas <FaultRule> dalam XML konfigurasi dan berfungsi menurun, mengevaluasi <Condition> dari setiap <FaultRule> ("outer" kondisi, bukan "bagian dalam" kondisi <Step>).
2. Mengeksekusi FaultRule pertama yang kondisinya benar. Jika FaultRule memiliki tidak ada kondisi, nilainya benar secara {i>default<i}.
   • Ketika FaultRule dijalankan, semua Langkah di dalam FaultRule dievaluasi secara berurutan, dari atas ke bawah dalam konfigurasi XML. Langkah tanpa kondisi akan dijalankan secara otomatis (kebijakan dijalankan), dan Langkah-langkah yang memiliki <Condition> yang mengevaluasi ke "true" dieksekusi (kondisi yang bernilai "false" tidak dijalankan).

   • Jika FaultRule dijalankan, tetapi tidak ada Langkah di FaultRule yang dijalankan (karena kondisi dievaluasi ke "false"), pesan error default yang dibuat Edge akan ditampilkan ke aplikasi klien. <DefaultFaultRule> tidak dieksekusi, karena Edge telah mengeksekusi satu FaultRule-nya.

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

Berikut adalah contoh dengan komentar inline.

Eksekusi ProxyEndpoint

Evaluasi ProxyEndpoint FaultRules dari bawah ke atas, jadi mulailah membaca dari bagian terakhir FaultRule dalam contoh berikut dan lanjutkan. Lihat terakhir DefaultFaultRule.

<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 dari atas ke bawah, jadi mulailah membaca FaultRule dalam contoh berikut dan lanjutkan. Lihat terakhir DefaultFaultRule.

<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 dapat Anda lihat pada contoh sebelumnya, urutan untuk memasukkan FaultRules adalah penting tergantung pada apakah kesalahan terjadi di {i>ProxyEndpoint<i} versus TargetEndpoint.

Contoh:

Kebijakan yang akan disertakan

Anda dapat menjalankan kebijakan apa pun dari FaultRule dengan menempatkannya dalam Langkah-Langkah. Sebagai contoh, Anda dapat jalankan kebijakan MenetapkanMessage untuk memformat respons ke aplikasi klien, lalu mencatat pesan ke dalam log dengan kebijakan MessageLogging. Kebijakan dijalankan sesuai urutan yang Anda masukkan (dari atas ke bawah dalam XML).

Aturan error HANYA dipicu dalam status error (tentang continueOnError)

Judulnya mungkin tampak seperti kita mengulang sendiri, tetapi ada satu hal yang perlu diwaspadai sehubungan dengan error proxy yang menyebabkan proxy API memasuki status error—atau tetapi, tidak memasukkan status error: atribut continueOnError pada lebih lanjut.

Sebagai ringkasan: Proxy API mengevaluasi <FaultRules> dan <DefaultFaultRule> hanya jika proxy memasuki status error. Bahwa berarti bahwa meskipun kondisi FaultRule bernilai benar (true), kondisi ini tidak akan terpicu jika proxy tidak dalam status error.

Namun, berikut adalah contoh error yang terjadi dan proxy tidak memasuki status error. Aktif kebijakan apa pun, Anda dapat menetapkan atribut pada elemen induk yang disebut continueOnError. Atribut tersebut sangat penting dalam hal penanganan fault, karena atribut ini menentukan apakah {i>proxy<i} tidak memasuki status {i>error<i} jika kebijakan tersebut gagal. Dalam kebanyakan kasus, Anda perlu 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 terjadi kegagalan Service Pemanggilan untuk menghentikan eksekusi proxy), proxy tidak akan memasuki status error jika tindakan tersebut kebijakan gagal, dan proxy tidak akan melihat FaultRules Anda.

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

Lokasi untuk menentukan FaultRules: ProxyEndpoint atau TargetEndpoint

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

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

Contoh lainnya, Jika kebijakan RaiseFault ada di <ProxyEndpoint> memicu error, FaultRule di <TargetEndpoint> tidak akan mendapatkan telah dijalankan.

FaultRules vs. kebijakan RaiseFault

Aturan kesalahan dan kebijakan RaiseFault mungkin terkesan seperti cara alternatif untuk menyelesaikan penanganan kesalahan; dan memang benar. Tetapi mereka juga bekerja sama. Ini menjelaskan hubungan di antara keduanya. Memahami hubungan ini akan membantu merancang penanganan kesalahan, terutama jika Anda ingin menggunakan keduanya.

Singkatnya:

• Aturan kesalahan selalu dievaluasi saat proxy API mengalami error status.

• Kebijakan RaiseFault adalah cara menempatkan proxy API dalam status error ketika tidak terjadi {i>error<i}.

  Misalnya, jika Anda ingin menampilkan pesan {i>error<i} jika kode status HTTP dalam respons dari layanan target lebih besar dari 200, tambahkan kebijakan RaiseFault di respons Anda alur kerja. 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 menyebabkan proxy mengalami error , yang mungkin akan menjalankan FaultRule? Di sinilah segalanya bisa sedikit rumit. Jika kebijakan RaiseFault akan menampilkan pesan error dan FaultRule akan dipicu dan mengembalikan pesan {i>error<i}, apa yang akan dikembalikan ke aplikasi klien?

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

Berikut contoh setelan yang ditetapkan oleh kebijakan RaiseFault dan FaultRule, serta hal yang dikembalikan ke aplikasi klien. Contoh ini dirancang agar singkat, bukan untuk praktik terbaik.

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

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

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

Kondisi bangunan

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

Untuk menempatkan sisa bagian ini dalam konteks, berikut contoh aturan kesalahan yang memiliki lapisan luar Kondisi FaultRule dan kondisi Langkah 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 kebijakan kesalahan

Variabel fault.name dan {policy_namespace}.{policy_name}.failed tersedia saat kebijakan menampilkan error.

fault.name

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

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

Nama error akan muncul dalam pesan error default. Misalnya, error berikut bernama FailedToResolveAPIKey. Dalam hal ini, variabel {i>flow<i} 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 Error kebijakan referensi 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.

• Kebijakan RaiseFault: raisefault.failed (sama untuk semua kebijakan RaiseFault)
• Kebijakan VerifyAPIKey: oauthV2.{policy_name}.failed, untuk contoh, oauthV2.Verify-API-Key-1.failed
• Kebijakan kuota dan kebijakan SpikeArrest: ratelimit.{policy_name}.failed, misalnya, ratelimit.Quota-1.failed

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

Informasi selengkapnya

• Kondisi: Referensi kondisi dan Variabel flow dan kondisi

• Error: Referensi error kebijakan
• Variabel: Referensi variabel, dan melihat masing-masing variabel halaman referensi kebijakan untuk variabel yang tersedia di setiap kebijakan.

Praktik terbaik untuk penanganan kesalahan

Penanganan kesalahan adalah tugas desain arsitektur utama untuk pengembangan proxy API. Penting luangkan waktu untuk mencari tahu bagaimana dan kapan Anda akan menangani {i>error<i}, tentukan pesan, dan mendesain format pesan {i>error<i}. Setelah (atau saat) Anda mengetahui hal-hal itu, kemudian gunakan praktik terbaik ini untuk membantu Anda dalam implementasi penanganan kesalahan.

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

• Untuk setiap FaultRule, berikan "outer" <Condition> (seinduk dengan <Step>). Aturan error tanpa kondisi luar akan otomatis dievaluasi ke true. "Dalam" Kondisi langkah tidak digunakan untuk menentukan apakah FaultRule benar atau false. Kondisi langkah hanya dievaluasi setelah Edge mengeksekusi FaultRule yang memuatnya. Dalam FaultRule, biasanya ada beberapa Langkah dengan kebijakan Tetapkan Pesan (atau lainnya), masing-masing dengan kondisi Step.

• Untuk menangani error dalam beberapa kebijakan berjenis sama (misalnya, beberapa Kuota kebijakan), buat satu FaultRule per error kebijakan yang mungkin 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 tambahan yang perlu ditangani, Anda dapat kembali nanti dan menambahkannya ke FaultRules. Tidak apa-apa untuk bersifat iteratif, meskipun memang memerlukan deployment ulang proxy.) Pendekatan ini memungkinkan Anda untuk menangkap jenis kesalahan yang sama kebijakan akan menampilkannya, sehingga membuat XML FaultRules Anda efisien.

  Kemudian, gunakan kondisi Langkah dalam jika Anda memerlukan kontrol error yang lebih mendetail. Misalnya, jika Anda menerapkan kuota developer individu dan kuota global dengan dua kebijakan di alur permintaan, setel "outer" Kondisi FaultRule yang akan dipicu pada Error QuotaViolation (yang ditampilkan saat kuota terlampaui dalam kedua kasus tersebut). Selanjutnya menetapkan Kondisi langkah untuk mengevaluasi variabel exceed.count di kedua kuota Anda kebijakan izin yang relevan. Hanya error yang relevan yang dikirim ke klien (kelebihan kuota developer atau error global kelebihan kuota). 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 saat Anda menggunakan satu kebijakan dari satu jenis, pertimbangkan satu error yang dijalankan ketika satu kebijakan itu gagal, dan menyertakan beberapa langkah yang dipetakan ke tiap kemungkinan kesalahan. 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 klien . Kebijakan Menetapkan Pesan cocok untuk hal ini. Pertimbangkan juga untuk mencatat pesan menggunakan kebijakan MessageLogging jika Anda ingin melacak error.
• Saat menggunakan kebijakan RaiseFault bersama dengan FaultRules, koordinasikan respons yang dikirim kembali saat kebijakan RaiseFault dan FaultRule menampilkan data. Sebagai misalnya, jika kebijakan RaiseFault mereset kode status HTTP, jangan reset FaultRule kode status. Hal terburuk yang dapat terjadi adalah kode status {i>default<i} dikembalikan ke aplikasi klien.
• <DefaultFaultRule> eksekusi:
  • Jika Anda ingin <DefaultFaultRule> selalu dijalankan saat tidak ada FaultRule dijalankan, jangan sertakan <Condition>.
  • Jika Anda ingin <DefaultFaultRule> selalu dijalankan bahkan saat elemen lain FaultRule telah dieksekusi, tambahkan Elemen turunan <AlwaysEnforce>true</AlwaysEnforce>.

Pola untuk penanganan fault 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 halaman Kembangkan tampilan untuk proxy API, atau edit file XML yang menentukan ProxyEndpoint atau TargetEndpoint.

Jika Anda membuat FaultRules di UI pengelolaan, buat kebijakan yang ingin dijalankan terlebih dahulu, lalu menambahkannya ke konfigurasi FaultRule. (Anda akan mendapatkan pesan error di UI jika mencoba menyimpan FaultRule yang mereferensikan kebijakan yang belum dibuat.)

Menambahkan kebijakan ke FaultRule

Meskipun Anda dapat memasukkan kebijakan apa pun dalam FaultRule, biasanya Anda menggunakan Menetapkan kebijakan untuk membuat pesan respons kustom untuk kondisi error. MenetapkanMessage memungkinkan Anda untuk mengonfigurasi respons HTTP dengan {i>payload<i}, kode status HTTP, {i>header<i}, dan alasan.

Contoh di bawah ini menunjukkan konfigurasi kebijakan Menetapkan Pesan standar:

<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>

Sekarang Anda dapat menggunakan kebijakan ini di FaultRule. Perhatikan bagaimana Anda mereferensikan MenetapkanMessage kebijakan menurut nama dalam 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 menjalankan kebijakan MenetapkanMessage yang dipanggil fault_invalidkey setiap kali aplikasi menyajikan kunci API yang tidak valid.

Anda dapat menjalankan beberapa kebijakan dalam 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 akan dijalankan sesuai urutan yang ditentukan. Misalnya, Anda dapat menggunakan Kebijakan MessageLogging, kebijakan ExtractVariables, Kebijakan Menetapkan Pesan, atau kebijakan lainnya dalam FaultRule. Perlu diperhatikan bahwa pemrosesan FaultRule akan langsung berhenti jika salah satu dari situasi ini terjadi:

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

Mendefinisikan pesan error kustom yang ditampilkan dari FaultRule

Sebagai praktik terbaik, Anda harus menentukan respons kesalahan yang jelas dari Google Cloud Platform. Dengan begitu, Anda dapat memberikan informasi yang konsisten dan bermanfaat kepada klien.

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

<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 mencakup:

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

Membuat DefaultFaultRule

DefaultFaultRule bertindak sebagai pengendali pengecualian untuk setiap error yang tidak ditangani secara eksplisit oleh {i>FaultRule<i} lainnya. Jika kondisi untuk semua FaultRules tidak cocok dengan error, DefaultFaultRule menangani error. Aktifkan penanganan fault default dengan menambahkan atribut Tag <DefaultFaultRule> sebagai elemen turunan ProxyEndpoint atau TargetEndpoint.

Misalnya, konfigurasi TargetEndpoint di bawah menetapkan 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 otomatis, seperti pesan yang berisi informasi kontak untuk dukungan teknis. Default ini memiliki fungsi ganda, yaitu memberikan informasi yang mudah digunakan developer, mengaburkan URL backend atau informasi lain yang mungkin digunakan untuk menyusupi sistem.

Misalnya, Anda menentukan kebijakan MenetapkanMessage 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> di <DefaultFaultRule> untuk menjalankan DefaultFaultRule untuk setiap error, bahkan jika FaultRule lain sudah dijalankan. DefaultFaultRule selalu merupakan FaultRule terakhir untuk mengeksekusi:

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

Salah satu kegunaan DefaultFaultRule adalah untuk menentukan jenis error yang jika tidak, mereka tidak dapat menentukannya. Misalnya, proxy API Anda gagal karena error yang tidak dapat ditentukan. Gunakan DefaultFaultRule untuk memanggil kebijakan TetapkanMessage berikut. Ini kebijakan menulis nilai fault.name ke header bernama DefaultFaultHeader dalam responsnya:

<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 {i>error<i}.

Menambahkan pencatatan pesan ke PostClientFlow

PostClientFlow adalah satu-satunya alur yang dijalankan setelah proxy memasuki error status. Hanya kebijakan MessageLogging yang dapat disertakan ke alur ini, yang akan dijalankan setelah respons dikirim kembali ke klien. Meskipun melampirkan kebijakan MessageLogging ke alur ini adalah secara teknis tidak penanganan {i>error<i}, Anda dapat menggunakannya untuk mencatat informasi jika terjadi kesalahan. Karena hal itu terlepas dari apakah {i>proxy<i} berhasil atau gagal, Anda bisa menempatkan {i>Message Logging<i} kebijakan di PostClientFlow dan dijamin selalu dieksekusi.

Menangani kesalahan 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 itu karena nilai {i>default<i} dari continueOnError elemen kebijakan adalah false, artinya saat terjadi dalam kebijakan, kontrol diarahkan ke status error. Setelah berada dalam status {i>error<i}, Anda tidak bisa mengembalikan kontrol ke pipeline normal dan biasanya Anda akan memunculkan beberapa ke aplikasi panggilan.

Namun, jika Anda menetapkan elemen continueOnError ke true untuk kebijakan, kontrol tetap berjalan saat ini dan kebijakan berikutnya dalam pipeline dijalankan setelah kebijakan yang menyebabkan error. Keuntungan menangani {i>error<i} dalam alur saat ini adalah bahwa Anda mungkin memiliki cara untuk memulihkan dari kesalahan untuk menyelesaikan pemrosesan permintaan.

Di bawah ini adalah kebijakan VerifyAPIKey bernama verify-api-key dengan Elemen continueOnError disetel 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 memproses berlanjut dengan aliran 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 selanjutnya dalam PreFlow menggunakan kondisi untuk menguji keberadaan {i>error<i}. Jika terjadi error dalam kebijakan VerifAPIKey, maka kebijakan bernama FaultInFlow kebijakan dijalankan. Jika tidak, kebijakan FaultInFlow akan dilewati. Kebijakan FaultInFlow dapat melakukan banyak hal, seperti mencatat error ke dalam log, mencoba memperbaiki {i>error<i}, atau melakukan beberapa tindakan lainnya.

Memicu error dengan menggunakan RaiseFault kebijakan

Anda dapat menggunakan kebijakan RaiseFault kapan saja dalam satu alur untuk memicu error. Ketika seorang Kebijakan RaiseFault dijalankan, kebijakan ini menghentikan alur saat ini dan mentransfer kontrol ke error status.

Salah satu kegunaan kebijakan RaiseFault adalah untuk menguji kondisi tertentu di mana kebijakan lain mungkin tidak dapat dideteksi. 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 ke status error. Atau, Anda dapat menyisipkan kebijakan RaiseFault dalam alur untuk melakukan 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 akan diuji untuk kesalahan bernama RaiseFault. RaiseFault kebijakan selalu menetapkan nilai fault.name ke RaiseFault.

Penanganan kustom kode error HTTP dari server target

Contoh yang ditunjukkan di bagian sebelumnya berlaku untuk error yang dibuat oleh kebijakan. Bagaimanapun cara Anda juga dapat membuat respons khusus untuk error tingkat transport, yang berarti error HTTP ditampilkan 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 HTTP kode respons di rentang 4xx-5xx sebagai 'failure'. Itu berarti setiap respons dari backend dengan kode respons HTTP 4xx-5xx secara otomatis memanggil status {i>error<i}, yang kemudian mengembalikan pesan {i>error<i} secara langsung kepada 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 'failure' tetapi hanya 5xx, atau Anda mungkin ingin untuk menampilkan pesan {i>error<i} khusus untuk kode respons HTTP 400 dan 500.

Pada contoh berikutnya, Anda menggunakan properti success.codes untuk mengonfigurasi TargetEndpoint untuk memperlakukan kode respons HTTP 400 dan 500 sebagai berhasil, bersama dengan HTTP default kode program. Dengan memperlakukan kode tersebut sebagai berhasil, TargetEndpoint mengambil alih pemrosesan pesan respons, alih-alih 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 rentang nilai-nilai..

Menetapkan properti success.codes akan menimpa nilai default-nya. Oleh karena itu, jika ingin menambahkan kode HTTP 400 ke daftar keberhasilan default kode, 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 untuk menampilkan pesan respons ke aplikasi yang meminta. TargetEndpoint berikut menggunakan kebijakan yang 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 salah

Layanan API mengatur kesalahan ke dalam kategori dan subkategori berikut.

Error selalu disertai dengan deskripsi teks alasan kegagalan tersebut. Jika sistem menimbulkan kesalahan, serangkaian atribut diisi untuk membantu dalam pemecahan masalah. Kesalahan mencakup informasi berikut:

• Alasan
• Atribut khusus yang ditentukan pengguna