Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Menghasilkan pesan khusus sebagai respons terhadap kondisi error. Gunakan RaiseFault untuk menentukan respons error yang ditampilkan ke aplikasi yang meminta saat terjadi kondisi tertentu.
Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.
Untuk informasi umum tentang penanganan kesalahan, lihat Menangani kesalahan.
Sampel
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> </Set> </FaultResponse> </RaiseFault>
Menampilkan Payload FaultResponse
Contoh yang lebih kompleks melibatkan ditampilkannya 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 Apigee 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> </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 pemanggilan layanan
Tentang kebijakan RaiseFault
Apigee memungkinkan Anda melakukan penanganan pengecualian kustom menggunakan kebijakan jenis RaiseFault. Kebijakan RaiseFault, yang mirip dengan kebijakan TetapkanMessage, memungkinkan Anda menghasilkan 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 fault 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 mentransfer kontrol dari alur saat ini ke alur Error, yang kemudian menampilkan respons kesalahan yang ditetapkan ke aplikasi klien yang meminta. Ketika Flow pesan beralih ke alur Error, tidak ada pemrosesan kebijakan lebih lanjut yang terjadi. Semua Langkah pemrosesan yang tersisa akan diabaikan, dan respons fault akan ditampilkan langsung ke aplikasi yang meminta.
Anda dapat menggunakan RaiseFault di ProxyEndpoint atau TargetEndpoint. Biasanya, Anda akan menambahkan Condition ke kebijakan RaiseFault. Setelah RaiseFault dijalankan, Apigee akan menjalankan fault processing 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 sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
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 |
---|---|
Kehadiran | Opsional |
Jenis | String |
Elemen <IgnoreUnresolvedVariables>
(Opsional) Mengabaikan error variabel yang belum terselesaikan dalam Flow. Nilai valid: benar/salah.
true
default.
Elemen <FaultResponse>
(Opsional) Mendefinisikan pesan respons yang ditampilkan ke klien yang meminta. FaultResponse menggunakan setelan yang sama dengan kebijakanAssignMessage.
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 dalam kebijakan RaiseFault. Selain itu, kebijakan yang disertakan pada FaultRule dapat mengakses variabel. Misalnya, kebijakan AssignMessage berikut menggunakan variabel yang ditetapkan dalam 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> </AssignMessage>
<AssignVariable>
dalam kebijakan RaiseFault menggunakan sintaksis yang sama dengan elemen <AssignVariable>
dalam kebijakanAssignMessage.
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 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 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/> </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>
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 |
Opsional | String |
variablePrefix | Secara opsional, tentukan pemisah utama pada variabel alur karena payload JSON tidak dapat menggunakan karakter "{" default. | Opsional | Karakter |
variableSuffix | Secara opsional, tentukan pemisah akhir pada variabel alur 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 <ShortFaultReason>
Menyatakan 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 memungkinkan perilaku dinamis kebijakan dan Flow saat runtime, berdasarkan header HTTP, konten pesan, atau konteks Flow. Variabel Flow yang telah ditentukan berikut ini 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 ini ilustrasi yang akan dilakukan 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
{ "fault":{ "detail":{ "errorcode":"steps.raisefault.RaiseFault" }, "faultstring":"Raising fault. Fault name: [name]" } }
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd
). Untuk referensi, skema kebijakan tersedia di GitHub.
Topik terkait
Lihat Menangani kesalahan