Menangani kesalahan

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

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 ditangani di Apigee.

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.

Video Deskripsi
Pengantar penanganan kesalahan dan alur error Pelajari penanganan fault dan hal yang terjadi saat terjadi error di proxy API.
Menangani kesalahan menggunakan aturan kesalahan Pelajari cara menangani kesalahan menggunakan aturan kesalahan.
Ajukan kustom kesalahan menggunakan kebijakan RaiseFault Menampilkan kesalahan kustom selama runtime API menggunakan kebijakan RaiseFault.
Menentukan kesalahan aturan di proxy API dan endpoint target Menentukan aturan kesalahan di proxy API dan endpoint target serta memahami perbedaan tersebut.
Memahami urutan eksekusi aturan fault Memahami urutan eksekusi aturan kesalahan di proxy dan target API endpoint.
Tentukan default aturan fault Tentukan aturan kesalahan default untuk menangani error generik di API Anda.

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 unavailable 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 mengetahui contoh lainnya, lihat postingan Komunitas Apigee ini:

Tindakan proxy API saat terjadi error

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

Keluar dari pipeline proxy

Ketika proxy API mengalami error, bagaimanapun caranya 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 jika terjadi kesalahan, proxy mengirimkan pesan default yang dihasilkan Apigee sendiri.

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. Kebijakan Menetapkan 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.

Anda tidak perlu melampirkan kebijakan ke alur; Anda cukup membuatnya, seperti yang dijelaskan dalam Buat kebijakan.

Berikut adalah contoh kebijakan Menetapkan Pesan 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 Unauthorized default untuk frasa 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>
    </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>: Apigee mengevaluasi kondisi dan mengeksekusi kebijakan hanya jika kondisinya benar. Jika ada beberapa {i>FaultRules<i} yang bernilai true, Apigee menjalankan pernyataan pertama yang 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 kustom, bukan pesan default samar yang dibuat oleh Apigee. 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 Apigee dalam menangani FaultRules, dari caranya diterima di satu FaultRule yang akan dieksekusi ke cara penanganan kondisi Langkah dalam saat FaultRule 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, berikut adalah logika yang digunakan Apigee saat proxy API mengalami status error. Perlu diketahui bahwa ada sedikit perbedaan antara evaluasi FaultRules di ProxyEndpoint dan TargetEndpoint.

  1. Apigee mengevaluasi FaultRules di ProxyEndpoint atau TargetEndpoint, bergantung pada tempat error terjadi:
    • ProxyEndpoint - Apigee memulai dengan bagian bawah <FaultRule> dalam XML konfigurasi dan berjalan, mengevaluasi <Condition> dari setiap <FaultRule> (bagian luar kondisi, bukan kondisi <Step> dalam).
    • TargetEndpoint - Apigee dimulai dari bagian teratas <FaultRule> dalam XML konfigurasi dan berfungsi menurun, mengevaluasi <Condition> dari setiap <FaultRule> (bagian luar kondisi, bukan kondisi <Step> dalam).
  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 dieksekusi (kondisi yang mengevaluasi ke code tidak dijalankan).

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

  3. Jika tidak ada FaultRule yang dijalankan, Apigee akan menjalankan <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), 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 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, 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 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:

Urutan ProxyEndpoint Urutan TargetEndpoint

Pada contoh berikut, karena evaluasi dari bawah ke atas, {i>FaultRule<i} 3 dieksekusi, yang berarti {i>FaultRules<i} 2 dan 1 tidak dievaluasi.

5. FaultRule 1: FALSE

4. FaultRule 2: BENAR

3. FaultAturan 3: BENAR

2. FaultRule 4: FALSE

1. FaultAturan 5: FALSE

Pada contoh berikut, karena evaluasi dari atas ke bawah, {i>FaultRule<i} 2 dieksekusi, yang berarti FaultRules 3, 4, dan 5 tidak dievaluasi.

1. FaultRule 1: FALSE

2. FaultRule 2: BENAR

3. FaultAturan 3: BENAR

4. FaultRule 4: FALSE

5. FaultAturan 5: FALSE

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 saat Apigee mencari FaultRules.

Misalnya, jika server target tidak tersedia (kode status HTTP 503), proxy API akan digunakan ke 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, Anda menambahkan kebijakan RaiseFault di respons Anda alur kerja. Token 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.

Yang disetel oleh kebijakan RaiseFault dan FaultRule.

Aplikasi klien menerima:

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

<- Kebijakan aturan kesalahan menetapkan hal ini:

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

<- Kebijakan RaiseFault menetapkan 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 yang Anda lakukan untuk kondisi lain di Apigee, 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 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

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. Gunakan alat Debug dan Referensi kebijakan untuk membantu Anda mengetahui variabel dan data HTTP mana yang tersedia.

Informasi selengkapnya

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:

  • Di FaultRules, Anda dapat menentukan jenis kebijakan apa pun. Pola yang paling umum adalah menggunakan Kebijakan TetapkanMessage untuk menetapkan item tertentu dalam respons error yang tertunda. Anda juga dapat menggunakan Menetapkan Pesan untuk menetapkan variabel yang digunakan untuk tujuan lain, misalnya, untuk variabel yang direferensikan oleh kebijakan logging yang dijalankan di PostClientFlow, atau di FlowHooks. Pertimbangkan juga untuk membuat log pesan, misalnya dengan kebijakan MessageLogging atau Kebijakan ServiceKeterangan, jika Anda ingin mencatat error tertentu dalam kondisi kesalahan tertentu.
  • Jangan tetapkan kebijakan RaiseFault sebagai Langkah dalam FaultRule. Lebih baik menggunakan Kebijakan Menetapkan Pesan untuk menyetel atau mengubah elemen pesan, termasuk payload, header, atau kode status.
  • Untuk setiap FaultRule, atau untuk semua kecuali FaultRule yang terakhir dievaluasi, menyediakan <Condition> luar yang dilampirkan sebagai turunan dari elemen <FaultRule>. Kondisi eksekusi untuk FaultRule tanpa aturan eksplisit Kondisi yang ditentukan, secara implisit akan dievaluasi ke true. <Condition> dilampirkan sebagai turunan dari elemen <Step> tidak digunakan untuk menentukan apakah kondisi eksekusi untuk FaultRule bernilai true atau false. Kondisi langkah hanya dievaluasi setelah Apigee mengeksekusi FaultRule yang memuatnya. Dalam {i>FaultRule<i}, biasanya ada beberapa Langkah dengan kebijakan MenetapkanMessage (atau yang 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, lalu bedakan di antara error terpisah dengan Kondisi yang dilampirkan pada 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 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.

    Kondisi Langkah internal memberi Anda kontrol yang lebih mendetail. Misalnya, jika Anda menerapkan kuota developer individu dan kuota global dengan dua kebijakan di alur permintaan, setel kondisi FaultRule outer agar dipicu pada Error QuotaViolation (yang ditampilkan saat kuota terlampaui dalam kedua kasus tersebut). Selanjutnya tetapkan Kondisi langkah untuk mengevaluasi variabel exceed.count tertentu 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>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 lainnya, lihat diskusi tentang Penanganan kesalahan kebijakan 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. Cara ini membuat XML Anda tetap sederhana dengan menggunakan satu FaultRule, bukan beberapa FaultRules (satu untuk setiap jenis error). Misalnya, Anda dapat menentukan bahwa Langkah kebijakan MenetapkanMessage dijalankan dalam berbagai kondisi, 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 (sisi klien <ProxyEndpoint> atau sisi target <TargetEndpoint>). Sertakan FaultRules untuk setiap kebijakan yang muncul di setiap lokasi.
  • Saat menggunakan kebijakan RaiseFault bersama dengan FaultRules, koordinasikan respons yang dikirim kembali saat kebijakan RaiseFault dan FaultRule menampilkan data. Sebagai jika Anda memiliki kebijakan RaiseFault yang menyetel kode status HTTP, jangan konfigurasi Tetapkan Langkah Pesan dalam FaultRule yang direset kode status. Hal terburuk yang dapat terjadi adalah kode status {i>default<i} dikembalikan ke aplikasi klien.

  • Elemen <DefaultFaultRule> melengkapi <FaultRules> untuk memberi Anda kontrol lebih besar atas kebijakan yang dijalankan {i>proxy<i} saat menangani status fault. Jika Anda menentukan <DefaultFaultRule>, skrip akan dijalankan jika salah satu atau kedua hal berikut benar:

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

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

    Gunakan <DefaultFaultRule> dengan <AlwaysEnforce> ditetapkan ke true, jika Anda memiliki satu atau beberapa kebijakan yang Anda inginkan untuk selalu dijalankan oleh {i>proxy<i}, terlepas dari apakah FaultRule sebelumnya telah dijalankan. Salah satu kemungkinan skenario: misalkan Anda ingin menginjeksikan header ke dalam respons apakah permintaan {i>proxy<i} menimbulkan kesalahan atau tidak, dan apakah kesalahan telah tertangani sebelumnya. Maka Anda akan melampirkan kebijakan Menetapkan Pesan yang sesuai di Bagian <PostFlow>/<Response>, dan juga melampirkan kebijakan yang sama dalam <DefaultFaultRule> dengan <AlwaysEnforce> disetel ke true.

Pola untuk penanganan fault yang terpusat dan dapat digunakan kembali

An pola penanganan error untuk proxy Apigee menjelaskan pola penanganan kesalahan 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 Mengembangkan tampilan untuk proxy API, atau mengedit file XML yang menentukan ProxyEndpoint atau TargetEndpoint.

Jika Anda membuat FaultRules di UI Apigee, 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="AM-Invalid-Key">
  <Set>
      <Payload contentType="text/plain">That is an error.</Payload>
      <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Perhatikan bahwa perintah ini tidak menentukan elemen <AssignTo>. Ini berarti akan ditetapkan ke pesan standby, tergantung tempat kebijakan dilampirkan.

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>AM-Invalid-Key</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 AM-Invalid-Key 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>AM-Invalid-Key</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> dan Tag <StatusCode> untuk menentukan respons error yang dikirim kembali ke klien pada error InvalidApiKey (lihat FaultRules sebelumnya contoh).

<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 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 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 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="AM-Return-Generic-Error">
  <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>AM-Return-Generic-Error</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

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

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

Selanjutnya, Anda dapat melihat header di alat Debug 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 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 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 VerifyAPIKey, 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 data tersebut ditransfer 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-HERE</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. Anda juga dapat mengatur variabel khusus dalam kebijakan RaiseFault. Jika demikian, Anda dapat menguji variabel tersebut di dalam elemen Condition.

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, Apigee memperlakukan kode respons HTTP dalam rentang 1xx-3xx sebagai berhasil, dan HTTP kode respons dalam rentang 4xx-5xx sebagai gagal. Itu berarti setiap respons dari backend dengan kode respons HTTP 4xx-5xx akan otomatis memanggil status error, 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 "kegagalan" tetapi hanya 5xx, atau Anda mungkin mau untuk menampilkan pesan error kustom 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 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..

Menyetel properti success.codes akan menimpa nilai default-nya. Oleh karena itu, jika Anda 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 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 400 dan 500 HTTP:

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

Kategori Subkategori Nama Kesalahan Deskripsi
Pesan Kegagalan yang terjadi selama alur pesan (tidak termasuk kegagalan kebijakan)
Kesalahan kustom {fault_name} Setiap kesalahan yang secara eksplisit ditangani oleh proxy API menggunakan kebijakan RaiseFault
Kode respons InternalServerError, Tidak Ditemukan Kode error HTTP 5xx, 4xx
Kegagalan pemilihan rute NoRoutesMatched Gagal memilih TargetEndpoint bernama untuk permintaan
Kegagalan klasifikasi NotFound Kegagalan disebabkan oleh URI permintaan yang tidak cocok dengan BasePath mana pun untuk ProxyEndpoint mana pun (yaitu, tidak ada proxy API yang cocok dengan URL di permintaan aplikasi klien)
Transpor Error tingkat transpor HTTP
Konektivitas ConnectionRefused, ConnectionReset, ConnectionTimeout Terjadi kegagalan saat membuat koneksi tingkat jaringan atau transport
Minta validasi ContentLengthMissing, HostHeaderMissing Kesalahan terjadi selama pemeriksaan semantik pada setiap permintaan
Validasi respons Kesalahan terjadi selama pemeriksaan semantik pada setiap respons
Error IO SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Error baca/tulis di endpoint klien atau target, waktu tunggu, error TLS/SSL, dan potongan kesalahan
Sistem Error runtime yang tidak ditentukan
Memori OutOfMemory, GCOverLimit Kegagalan terkait memori
Rangkaian pesan RogueTaskTerminated Kegagalan seperti penghentian tugas yang tidak sedang dijalankan
Kebijakan Kesalahan untuk setiap jenis kebijakan ditentukan dalam Referensi kebijakan.

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