Kebijakan RaiseFault

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Apa

Menghasilkan pesan kustom sebagai respons terhadap kondisi error. Gunakan RaiseFault untuk menentukan respons kesalahan yang ditampilkan ke aplikasi yang meminta ketika muncul kondisi tertentu.

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua perlu diketahui pengguna tentang jenis kebijakan dan lingkungan. Sebagai informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

Untuk informasi umum tentang penanganan kesalahan, lihat Menangani kesalahan.

Sampel

Tampilkan FaultResponse

Pada penggunaan yang paling umum, RaiseFault digunakan untuk mengembalikan respons kesalahan khusus ke aplikasi yang meminta. Misalnya, kebijakan ini akan menampilkan kode status 404 dengan tidak ada payload:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

Tampilkan Payload FaultResponse

Contoh yang lebih kompleks melibatkan pengembalian payload respon kesalahan khusus, bersama dengan HTTP header dan kode status HTTP. Pada contoh berikut, respons fault diisi dengan pesan XML berisi kode status HTTP yang diterima oleh Apigee dari backend layanan, dan header yang berisi jenis kesalahan yang terjadi:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact [e-mail]</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Untuk daftar semua variabel yang tersedia untuk mengisi FaultResponse secara dinamis pesan, lihat Variabel referensi

Menangani error info layanan

Contoh: Belajar sambil melakukan!
Pelajari contoh Apigee menunjukkan cara memeriksa kode HTTP dalam respons ServiceInfo dan menampilkan pengecualian kustom berdasarkan nilai kode. Contoh menampilkan pesan error kustom saat layanan target menampilkan status 404. Cukup clone repositori Anda dan ikuti petunjuk dalam topik tersebut. Contoh tersebut menggambarkan untuk menangani error info layanan. .

---

Tentang kebijakan RaiseFault

Apigee memungkinkan Anda melakukan penanganan pengecualian kustom menggunakan kebijakan jenis RaiseFault. Kebijakan RaiseFault, yang mirip dengan Kebijakan TetapkanMessage, memungkinkan Anda membuat respons kesalahan khusus sebagai respons terhadap kondisi kesalahan.

Menggunakan kebijakan RaiseFault untuk menentukan respons kesalahan yang ditampilkan ke aplikasi yang meminta saat kondisi error tertentu muncul. Respons fault dapat terdiri dari header HTTP, kueri parameter, dan payload pesan. Respons kesalahan kustom dapat lebih berguna bagi developer aplikasi dan pengguna akhir aplikasi daripada pesan kesalahan umum atau kode respons HTTP.

Saat dijalankan, kebijakan RaiseFault mentransfer kontrol dari alur saat ini ke Error , yang kemudian menampilkan respons kesalahan yang ditetapkan ke aplikasi klien yang meminta. Jika Alur pesan beralih ke Alur error, tidak ada pemrosesan kebijakan lebih lanjut yang terjadi. Semua yang tersisa Langkah pemrosesan diabaikan, dan respons fault ditampilkan langsung ke permintaan .

Anda dapat menggunakan RaiseFault di ProxyEndpoint atau TargetEndpoint. Biasanya, Anda akan memasang Kondisi ke kebijakan RaiseFault. Setelah RaiseFault dijalankan, Apigee akan menjalankan fault processing, mengevaluasi FaultRules, atau jika tidak ada aturan fault yang ditentukan, pemrosesan akan dihentikan permintaan.

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> atribut

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:

Atribut	Deskripsi	Default	Kehadiran
name	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.	T/A	Diperlukan
continueOnError	Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani kesalahan dalam alur saat ini	false	Opsional
enabled	Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.	true	Opsional
async	Atribut ini sudah tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

&lt;IgnoreUnresolvedVariables&gt; elemen

(Opsional) Mengabaikan error variabel yang belum terselesaikan dalam Alur. Nilai valid: benar/salah. true default.

&lt;FaultResponse&gt; elemen

(Opsional) Menentukan pesan respons yang ditampilkan ke klien yang meminta. FaultResponse menggunakan setelan yang sama dengan kebijakan TetapkanMessage.

&lt;FaultResponse&gt;&lt;AssignVariable&gt; elemen

Menetapkan nilai ke variabel alur tujuan. Jika variabel flow tidak ada, AssignVariable akan membuatnya.

Misalnya, gunakan kode berikut untuk menetapkan variabel bernama myFaultVar dalam kebijakan RaiseFault:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Kemudian, Anda dapat merujuk ke variabel tersebut dalam template pesan nanti dalam kebijakan RaiseFault. Selain itu, kebijakan yang dilampirkan ke FaultRule kemudian dapat mengakses variabel tersebut. Misalnya, Kebijakan TetapkanMessage menggunakan variabel yang disetel di RaiseFault untuk menyetel Header di respons kesalahan:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignVariable> dalam kebijakan RaiseFault menggunakan sintaksis yang sama dengan Elemen <AssignVariable> di kebijakan MenetapkanMessage.

&lt;FaultResponse&gt;&lt;Add&gt;/&lt;Headers&gt; elemen

Menambahkan header HTTP ke pesan error. Perhatikan bahwa header kosong <Add><Headers/></Add> tidak menambahkan header apa pun. Ini menyalin nilai variabel alur request.user.agent ke dalam {i>header<i}.

Elemen <Header> mendukung fitur substitusi string dinamis yang disebut template pesan.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

&lt;FaultResponse&gt;&lt;Copy&gt; elemen

Menyalin informasi dari pesan yang ditentukan oleh source ke pesan error.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

Atribut

 <Copy source="response">

Atribut	Deskripsi	Kehadiran	Jenis
sumber	Menentukan objek sumber salinan. Jika source tidak ditetapkan, maka diperlakukan sebagai pesan sederhana. Misalnya, jika kebijakan berada di alur permintaan, lalu sumber ditetapkan secara default ke objek request. Jika kebijakan dalam alur respons, secara default objek response. Jika Anda menghilangkan source, Anda dapat menggunakan referensi absolut ke variabel alur sebagai sumber salinan. Misalnya, sebutkan nilainya sebagai {request.header.user-agent}. Jika variabel sumber tidak dapat di-resolve, atau di-resolve menjadi jenis bukan pesan, <Copy> gagal merespons.	Opsional	String

&lt;FaultResponse&gt;&lt;Copy&gt;/&lt;Headers&gt; elemen

Menyalin header HTTP yang ditentukan dari sumber ke pesan error. Untuk menyalin semua {i>header<i}, tentukan <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

Jika ada beberapa header dengan nama yang sama, gunakan sintaksis berikut:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

Contoh ini menyalin "h1", "h2", dan nilai kedua dari "h3". Jika "h3" hanya memiliki satu , maka tidak akan disalin.

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

&lt;FaultResponse&gt;&lt;Copy&gt;/&lt;StatusCode&gt; elemen

Kode status HTTP yang akan disalin dari objek yang ditentukan oleh atribut sumber ke error untuk membuat pesan email baru.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Default:	false
Kehadiran:	Opsional
Jenis:	String

&lt;FaultResponse&gt;&lt;Remove&gt;/&lt;Headers&gt; elemen

Menghapus header HTTP yang ditentukan dari pesan error. Untuk menghapus semua {i>header<i}, tentukan <Remove><Headers/></Remove>. Contoh ini menghapus header user-agent dari pesan.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Jika ada beberapa header dengan nama yang sama, gunakan sintaksis berikut:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

Contoh ini menghapus "h1", "h2", dan nilai kedua dari "h3". Jika "h3" hanya memiliki satu , maka tidak dihapus.

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

&lt;FaultResponse&gt;&lt;Set&gt; elemen

Menetapkan informasi dalam pesan error.

Sub-elemen <Set> mendukung fitur substitusi string dinamis yang disebut template pesan.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

Default:	T/A
Kehadiran:	Opsional
Jenis:	T/A

&lt;FaultResponse&gt;/&lt;Set&gt;/&lt;Headers&gt; elemen

Menetapkan atau menimpa header HTTP dalam pesan error. Perhatikan bahwa header kosong <Set><Headers/></Set> tidak menetapkan header apa pun. Contoh ini menetapkan header user-agent ke variabel pesan yang ditentukan dengan elemen <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

&lt;FaultResponse&gt;/&lt;Set&gt;/&lt;Payload&gt; elemen

Menetapkan payload pesan error.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Tetapkan payload JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

Dalam payload JSON, Anda dapat memasukkan variabel menggunakan variablePrefix dan Atribut variableSuffix dengan karakter pembatas seperti yang ditampilkan di bawah contoh.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

atau, mulai rilis cloud 16.08.17, Anda juga dapat menggunakan kurung kurawal untuk menyisipkan variabel:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Tetapkan payload campuran dalam XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Default:
Kehadiran:	Opsional
Jenis:	String

Atribut

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Atribut	Deskripsi	Kehadiran	Jenis
contentType	Jika contentType ditentukan, nilainya akan ditetapkan ke Content-Type {i>header<i}.	Opsional	String
variablePrefix	Secara opsional menentukan pembatas utama pada variabel alur karena payload JSON tidak dapat menggunakan "{"default <i} karakter.	Opsional	Karakter
variableSuffix	Secara opsional menentukan pembatas akhir pada alur karena payload JSON tidak dapat menggunakan "}" default karakter.	Opsional	Karakter

&lt;FaultResponse&gt;/&lt;Set&gt;/&lt;StatusCode&gt; elemen

Menetapkan kode status respons.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Default:	false
Kehadiran:	Opsional
Jenis:	Boolean

&lt;ShortFaultReason&gt; elemen

Menentukan untuk menampilkan alasan kesalahan singkat dalam respons:

<ShortFaultReason>true|false</ShortFaultReason>

Secara default, alasan kesalahan dalam respons kebijakan adalah:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Agar pesan lebih mudah dibaca, Anda dapat menyetel elemen <ShortFaultReason> ke true untuk mempersingkat faultstring menjadi nama kebijakan saja:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Nilai valid: true/false(default).

Default:	false
Kehadiran:	Opsional
Jenis:	Boolean

Variabel flow

Variabel flow memungkinkan perilaku dinamis kebijakan dan Flow saat runtime, berdasarkan HTTP header, konten pesan, atau konteks Alur. Variabel Flow yang telah ditentukan sebelumnya tersedia setelah kebijakan RaiseFault dijalankan. Untuk mengetahui informasi selengkapnya tentang variabel Alur, lihat Referensi variabel.

Variabel	Jenis	Izin	Deskripsi
fault.name	String	Hanya-Baca	Jika kebijakan RaiseFault dijalankan, variabel ini akan selalu disetel ke string RaiseFault.
fault.type	String	Hanya-Baca	Menampilkan jenis kesalahan dalam error dan jika tidak tersedia, string kosong.
fault.category	String	Hanya-Baca	Menampilkan kategori kesalahan dalam error dan, jika tidak tersedia, string kosong.

Contoh penggunaan RaiseFault

Contoh berikut menggunakan Kondisi untuk memberlakukan keberadaan queryparam dengan nama zipcode pada permintaan masuk. Jika bahwa queryparam tidak ada, alur akan memunculkan kesalahan melalui RaiseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

Hal berikut menggambarkan hal yang akan terjadi di RaiseFault:

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Hal yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan	Status HTTP	Penyebab
steps.raisefault.RaiseFault	500	Lihat string kesalahan.

Error saat deployment

Tidak ada.

Variabel kesalahan

Variabel ini ditetapkan saat terjadi error runtime. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel	Dari mana	Contoh
fault.name="fault_name"	fault_name adalah nama kesalahannya, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan.	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan.	raisefault.RF-ThrowError.failed = true

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menjebak bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena bisa berubah.

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Topik terkait

Lihat Menangani kesalahan