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 dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.
Untuk mengetahui informasi umum tentang penanganan kesalahan, lihat Menangani kesalahan.
Sampel
Mengembalikan 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>
Payload FaultResponse yang Dikembalikan
Contoh yang lebih kompleks melibatkan menampilkan payload respons kesalahan 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 kesalahan 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 kesalahan 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 error yang ditetapkan ke aplikasi klien yang meminta. Saat Alur pesan beralih ke alur Error, tidak ada lagi pemrosesan kebijakan yang terjadi. Semua Langkah pemrosesan yang tersisa dilewati, dan respons kesalahan dikembalikan 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 kesalahan 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/> </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 umum untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke Tetapkan ke |
false | Opsional |
enabled |
Tetapkan ke Tetapkan ke |
benar | Opsional |
async |
Atribut ini tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Kehadiran | Opsional |
Jenis | String |
Elemen <IgnoreUnresolvedVariables>
(Opsional) Mengabaikan error variabel yang belum terselesaikan di Flow. Nilai yang valid: benar/salah.
Default true
.
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
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/> </Copy>
Default: |
T/A |
Kehadiran: |
Opsional |
Jenis: |
String |
Atribut
<Copy source="response">
Atribut | Deskripsi | Kehadiran | Jenis |
---|---|---|---|
sumber |
Menentukan objek sumber salinan.
|
Opsional | String |
Elemen <FaultResponse><Copy>/<Headers>
Menyalin header HTTP tertentu 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 sintaks 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, maka nilai tersebut tidak 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 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 sintaks 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, maka 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/> </Set>
Default: |
T/A |
Kehadiran: |
Opsional |
Jenis: |
T/A |
Elemen <FaultResponse>/<Set>/<Headers>
Menetapkan atau mengganti 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, mulai dari 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>
Menetapkan payload campuran di 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 |
Opsional | String |
variablePrefix | Secara opsional menentukan pembatas awal pada variabel alur karena payload JSON tidak dapat menggunakan karakter "{" default. | Opsional | Char |
variableSuffix | Secara opsional menentukan pembatas di akhir variabel aliran 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 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 benar (true) untuk memperpendek faultstring
menjadi hanya nama kebijakan:
"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}
Nilai yang valid: benar/salah(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 bawaan berikut tersedia setelah kebijakan RaiseFault dijalankan. Untuk mengetahui informasi selengkapnya tentang variabel Flow, lihat Referensi variabel.
Variabel | Jenis | Izin | Deskripsi |
---|---|---|---|
fault.name | String | Hanya Baca | Saat kebijakan RaiseFault dijalankan, variabel ini 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 menerapkan keberadaan
queryparam
dengan nama zipcode
pada permintaan masuk. Jika
queryparam
tersebut 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>
<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
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause |
---|---|---|
steps.raisefault.RaiseFault |
500 |
See fault string. |
Deployment errors
None.
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name = "RaiseFault" |
raisefault.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | raisefault.RF-ThrowError.failed = true |
Example error response
{ "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