Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan RaiseFault

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Apa

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

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Untuk informasi umum tentang penanganan error, lihat Menangani error.

Sampel

Menampilkan FaultResponse

Dalam penggunaan yang paling umum, RaiseFault digunakan untuk menampilkan respons error 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>
   </Set>
 </FaultResponse>
</RaiseFault>

Menampilkan Payload FaultResponse

Contoh yang lebih kompleks melibatkan pengembalian payload respons error kustom, beserta header HTTP dan kode status HTTP. Dalam contoh berikut, respons error diisi dengan pesan XML yang berisi kode status HTTP yang diterima oleh Apigee dari layanan backend, dan header yang berisi jenis error 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>
   </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 memungkinkan Anda melakukan penanganan pengecualian kustom menggunakan kebijakan jenis RaiseFault. Kebijakan RaiseFault, yang mirip dengan kebijakan AssignMessage, memungkinkan Anda membuat respons error kustom sebagai respons terhadap kondisi error.

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

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

Anda dapat menggunakan RaiseFault di ProxyEndpoint atau TargetEndpoint. Biasanya, Anda akan melampirkan Kondisi ke kebijakan RaiseFault. Setelah RaiseFault dieksekusi, Apigee akan melakukan pemrosesan error normal, mengevaluasi FaultRules, atau jika tidak ada aturan error yang ditentukan, API ini 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <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	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

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

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.

Kehadiran Opsional

Jenis String

Elemen <IgnoreUnresolvedVariables>

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

Elemen <FaultResponse>

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

Elemen <FaultResponse><AssignVariable>

Menetapkan nilai ke variabel alur tujuan. Jika variabel alur 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 di kebijakan RaiseFault. Selain itu, kebijakan yang dilampirkan ke FaultRule kemudian dapat mengakses variabel. Misalnya, kebijakan AssignMessage berikut menggunakan variabel yang ditetapkan di RaiseFault untuk menetapkan Header dalam respons error:

<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> dalam kebijakan AssignMessage.

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

Elemen <Header> mendukung fitur penggantian 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

Elemen <FaultResponse><Copy>

Menyalin informasi dari pesan yang ditentukan oleh atribut 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 ditentukan, pesan tersebut akan diperlakukan sebagai pesan sederhana. Misalnya, jika kebijakan berada dalam alur permintaan, sumber akan ditetapkan secara default ke objek request. Jika kebijakan berada dalam flow respons, kebijakan akan ditetapkan secara default ke objek response. Jika Anda menghapus source, Anda dapat menggunakan referensi absolut ke variabel alur 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> gagal merespons.	Opsional	String

Atribut

Deskripsi

Kehadiran

Jenis

sumber

Menentukan objek sumber salinan.

Jika source tidak ditentukan, pesan tersebut akan diperlakukan sebagai pesan sederhana. Misalnya, jika kebijakan berada dalam alur permintaan, sumber akan ditetapkan secara default ke objek request. Jika kebijakan berada dalam flow respons, kebijakan akan ditetapkan secara default ke objek response. Jika Anda menghapus source, Anda dapat menggunakan referensi absolut ke variabel alur 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> 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 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><Remove>/<Headers>

Menghapus header HTTP yang ditentukan 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.

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

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </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 pemisah seperti yang ditunjukkan dalam contoh berikut.

<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 header `Content-Type`.	Opsional	String
variablePrefix	Secara opsional menentukan pemisah di awal pada variabel alur karena payload JSON tidak dapat menggunakan karakter "{" default.	Opsional	Char
variableSuffix	Secara opsional menentukan pemisah akhir pada variabel flow karena payload JSON tidak dapat menggunakan karakter "}" default.	Opsional	Char

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

Menetapkan kode status respons.

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

Default:	false
Kehadiran:	Opsional
Jenis:	Boolean

Elemen <ShortFaultReason>

Menentukan untuk menampilkan alasan kerusakan singkat dalam respons:

<ShortFaultReason>true|false</ShortFaultReason>

Secara default, alasan error 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 true untuk mempersingkat faultstring menjadi hanya nama kebijakan:

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

Nilai yang valid: true/false(default).

Default:	false
Kehadiran:	Opsional
Jenis:	Boolean

Variabel alur

Variabel alur memungkinkan perilaku dinamis kebijakan dan Alur saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Alur. Variabel Flow standar berikut tersedia setelah kebijakan RaiseFault dijalankan. Untuk informasi selengkapnya tentang variabel Flow, lihat Referensi variabel.

Variabel	Jenis	Izin	Deskripsi
fault.name	String	Hanya Baca	Saat kebijakan RaiseFault dieksekusi, variabel ini selalu ditetapkan ke string `RaiseFault`.
fault.type	String	Hanya Baca	Menampilkan jenis error dalam error dan jika tidak tersedia, string kosong.
fault.category	String	Hanya Baca	Menampilkan kategori error 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, alur akan memunculkan error 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 ini ilustrasi 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>
    </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 error