Kebijakan RaiseFault

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

Apa

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

Untuk mengetahui informasi umum tentang penanganan kesalahan, lihat Menangani kesalahan.

Contoh

Menampilkan FaultResponse

Dalam penggunaan yang paling umum, RaiseFault digunakan untuk menampilkan respons fault kustom ke aplikasi yang meminta. Misalnya, kebijakan ini akan menampilkan kode status 404 tanpa payload:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

Menampilkan Payload FaultResponse

Contoh yang lebih kompleks adalah menampilkan payload respons kesalahan kustom, bersama dengan header HTTP dan kode status HTTP. Dalam contoh berikut, respons fault diisi dengan pesan XML yang berisi kode status HTTP yang diterima oleh Edge dari layanan backend, dan header yang berisi jenis kesalahan yang terjadi:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Untuk mengetahui daftar semua variabel yang tersedia untuk mengisi pesan FaultResponse secara dinamis, lihat Referensi variabel

Menangani error info layanan


Tentang kebijakan RaiseFault

Apigee Edge memungkinkan Anda melakukan penanganan pengecualian kustom menggunakan kebijakan jenis RaiseFault. Kebijakan RaiseFault, yang mirip dengan kebijakanAssignMessage, memungkinkan Anda menghasilkan respons kesalahan kustom sebagai respons terhadap kondisi error.

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

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

Anda dapat menggunakan RaiseFault di ProxyEndpoint atau TargetEndpoint. Biasanya, Anda akan menambahkan Condition ke kebijakan RaiseFault. Setelah RaiseFault dieksekusi, Apigee akan melakukan fault processing secara normal, mengevaluasi FaultRules, atau jika tidak ada aturan kesalahan yang ditentukan, Apigee akan menghentikan pemrosesan 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/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Atribut <RaiseFault>

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

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.

Ketersediaan Opsional
Jenis String

Elemen <IgnoreUnresolvedVariables>

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

Elemen <FaultResponse>

(Opsional) Mendefinisikan pesan respons yang ditampilkan ke klien yang meminta. FaultResponse menggunakan setelan yang sama dengan kebijakanAssignMessage (tidak tersedia di Apigee Edge untuk Private Cloud).

Elemen <FaultResponse><AssignVariable>

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>

Anda kemudian dapat merujuk ke variabel tersebut dalam template pesan nanti dalam kebijakan RaiseFault. Selain itu, kebijakan yang dilampirkan pada FaultRule juga dapat mengakses variabel. Misalnya, kebijakan BiddingMessage berikut menggunakan variabel yang ditetapkan di RaiseFault untuk menetapkan Header dalam respons fault:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> dalam kebijakan RaiseFault menggunakan sintaksis yang sama dengan elemen <AssignVariable> dalam kebijakanAssignMessage. Perhatikan bahwa fungsi ini saat ini tidak tersedia di Apigee Edge untuk Private Cloud.

Elemen <FaultResponse><Add>/<Headers>

Menambahkan header HTTP ke pesan error. Perhatikan bahwa header kosong <Add><Headers/></Add> tidak menambahkan header apa pun. Contoh ini menyalin nilai variabel alur request.user.agent ke header.

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

Default:

T/A

Kehadiran:

Opsional

Jenis:

String

Elemen <FaultResponse><Copy>

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

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

Default:

T/A

Kehadiran:

Opsional

Jenis:

String

Atribut

 <Copy source="response">
Atribut Deskripsi Ketersediaan Jenis
source

Menentukan objek sumber salinan.

  • Jika source tidak ditentukan, maka akan diperlakukan sebagai pesan sederhana. Misalnya, jika kebijakan berada dalam alur permintaan, sumber akan ditetapkan secara default ke objek request. Jika kebijakan berada dalam alur respons, kebijakan akan ditetapkan secara default ke objek response. Jika menghilangkan sumber, Anda dapat menggunakan referensi absolut ke variabel flow sebagai sumber salinan. Misalnya, tentukan nilai sebagai {request.header.user-agent}.
  • Jika variabel sumber tidak dapat di-resolve, atau di-resolve ke jenis non-pesan, <Copy> akan gagal merespons.
Opsional String

Elemen <FaultResponse><Copy>/<Headers>

Menyalin header HTTP yang ditentukan dari sumber ke pesan error. Untuk menyalin semua header, 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 akan menyalin "h1", "h2", dan nilai kedua "h3". Jika "h3" hanya memiliki satu nilai, nilai tersebut tidak akan disalin.

Default:

T/A

Kehadiran:

Opsional

Jenis:

String

Elemen <FaultResponse><Copy>/<StatusCode>

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

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

Default:

false

Kehadiran:

Opsional

Jenis:

String

Elemen <FaultResponse><Copy>/<ReasonPhrase>

Deskripsi alasan untuk menyalin dari objek yang ditentukan oleh atribut sumber ke pesan error.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Default:

false

Kehadiran:

Opsional

Jenis:

String

Elemen <FaultResponse><Remove>/<Headers>

Menghapus header HTTP tertentu dari pesan error. Untuk menghapus semua header, 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 "h3". Jika "h3" hanya memiliki satu nilai, nilai tersebut tidak akan dihapus.

Default:

T/A

Kehadiran:

Opsional

Jenis:

String

Elemen <FaultResponse><Set>

Menetapkan informasi dalam pesan error.

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

Default:

T/A

Kehadiran:

Opsional

Jenis:

T/A

Elemen <FaultResponse>/<Set>/<Headers>

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

Elemen <FaultResponse>/<Set>/<Payload>

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 menyisipkan variabel menggunakan atribut variablePrefix dan variableSuffix dengan karakter pembatas seperti yang ditunjukkan dalam contoh berikut.

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

atau, pada rilis cloud 16.08.17, Anda juga dapat menggunakan tanda kurung kurawal untuk memasukkan variabel:

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

Setel 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 Ketersediaan Jenis
contentType

Jika contentType ditentukan, nilainya akan ditetapkan ke header Content-Type.

Opsional String
variablePrefix Secara opsional, tentukan pemisah di awal pada variabel flow karena payload JSON tidak dapat menggunakan karakter "{"" default. Opsional Karakter
variableSuffix Secara opsional, tentukan pembatas di akhir pada variabel flow karena payload JSON tidak dapat menggunakan karakter "}" default. Opsional Karakter

Elemen <FaultResponse>/<Set>/<StatusCode>

Menetapkan kode status respons.

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

Default:

false

Kehadiran:

Opsional

Jenis:

Boolean

Elemen <FaultResponse>/<Set>/<ReasonPhrase>

Menetapkan frasa alasan respons.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Default:

false

Kehadiran:

Opsional

Jenis:

Boolean

Elemen <ShortFaultReason>

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 menetapkan elemen <ShortFaultReason> ke benar (true) untuk mempersingkat faultstring menjadi nama kebijakan saja:

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

Nilai yang valid: true/false(default).

Default:

false

Kehadiran:

Opsional

Jenis:

Boolean

Variabel alur

Variabel flow mengaktifkan perilaku dinamis kebijakan dan Flow saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Alur. Variabel Alur yang telah ditetapkan berikut tersedia setelah kebijakan RaiseFault dieksekusi. Untuk informasi selengkapnya tentang variabel Alur, lihat Referensi variabel.

Variabel Jenis Izin Deskripsi
fault.name String Hanya Baca Saat kebijakan RaiseFault dijalankan, variabel ini selalu ditetapkan 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 menerapkan keberadaan queryparam dengan nama zipcode pada permintaan masuk. Jika queryparam tersebut tidak ada, flow 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>
Berikut mengilustrasikan hal yang akan ada 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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang disetel oleh Edge 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 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

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