Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Kebijakan SOAPMessageValidation melakukan hal berikut:
- Memvalidasi pesan XML apa pun terhadap skema XSD-nya
- Memvalidasi pesan SOAP terhadap definisi WSDL
- Menentukan bentuk pesan JSON dan XML yang baik
Meskipun nama kebijakan ini di UI adalah SOAPMessageValidation, kebijakan tersebut memvalidasi lebih dari sekadar pesan SOAP. Bagian ini merujuk pada kebijakan sebagai kebijakan MessageValidation.
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.
Elemen <MessageValidation>
Menentukan kebijakan MessageValidation.
Nilai Default | Lihat tab Kebijakan Default di bawah |
Wajib? | Opsional |
Type | Objek kompleks |
Elemen Induk | t/a |
Elemen Turunan |
<DisplayName> <Element> <ResourceURL> <SOAPMessage> <Source> |
Sintaksis
Elemen <MessageValidation>
menggunakan sintaksis berikut:
<MessageValidation continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <!-- All MessageValidation child elements are optional --> <DisplayName>policy_display_name</DisplayName> <Element namespace="element_namespace">element_to_validate</Element> <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/> <Source>message_to_validate</Source> <ResourceURL>validation_WSDL_or_XSD</ResourceURL> </MessageValidation>
Kebijakan Default
Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan MessageValidation ke alur di UI Apigee:
<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1"> <DisplayName>SOAP Message Validation-1</DisplayName> <Properties/> <Element namespace="http://sample.com">sampleObject</Element> <SOAPMessage/> <Source>request</Source> <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL> </MessageValidation>
Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
continueOnError |
false | Opsional | 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:
|
enabled |
true | Opsional | Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur. |
async |
false | Tidak digunakan lagi | Atribut ini sudah tidak digunakan lagi. |
Contoh
Contoh berikut menunjukkan beberapa cara untuk menggunakan kebijakan MessageValidation:
1: Validasi XSD
Anda dapat menggunakan kebijakan Message Validation untuk memvalidasi payload permintaan pesan XML terhadap skema XSD.
- Buat file resource XSD baru. Contoh,
note-schema.xsd
:<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="note"> <xs:complexType> <xs:sequence> <xs:element name="to" type="xs:string"/> <xs:element name="from" type="xs:string"/> <xs:element name="heading" type="xs:string"/> <xs:element name="body" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
- Tambahkan kebijakan Validasi Pesan SOAP ke pra-alur endpoint proxy Anda:
- Tentukan lokasi file resource XSD dengan elemen
<ResourceURL>
. Contoh:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- Hapus elemen
<SOAPMessage>
dan<Element>
dari definisi kebijakan.
Definisi kebijakan Anda akan terlihat seperti berikut:
<MessageValidation continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My XML Validator</DisplayName> <Properties/> <Source>request</Source> <ResourceURL>xsd://note-schema.xsd</ResourceURL> </MessageValidation>
- Tentukan lokasi file resource XSD dengan elemen
- Kirim permintaan
POST
ke proxy API Anda dengan XML sebagai payload pesan, seperti yang ditunjukkan contoh berikut:curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock -d '<note> <to>Fred Rogers</to> <from>Nick Danger</from> <heading>Greetings from my neighborhood</heading> <body>Just writing to say hello.</body> </note>'
Perhatikan bahwa header
Content-type
disetel keapplication/xml
.Anda juga dapat membuat file data untuk payload tersebut dan mereferensikannya dengan perintah seperti berikut:
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/note-payload.xml'
Anda akan menerima respons HTTP 200
. Bergantung pada endpoint target Anda, Anda mungkin menerima detail tambahan tentang permintaan tersebut. Misalnya, jika Anda menggunakan http://httpbin.org/post
sebagai endpoint target dan menentukan output -v
(panjang), responsnya akan serupa dengan berikut ini:
< HTTP/1.1 200 OK < Date: Wed, 16 May 2018 21:24:54 GMT < Content-Type: application/xml < Content-Length: 431 < Connection: keep-alive < Server: gunicorn/19.8.1 < Access-Control-Allow-Origin: * < Access-Control-Allow-Credentials: true < Via: 1.1 vegur { "args":{}, "data":"<note><to>fred</to><from>nick</from><heading>hello</heading> <body>Just writing to say hello.</body></note>", "files":{}, "form":{}, "headers": { "Accept":"*/*", "Connection":"close", "Content-Length":"106", "Content-Type":"application/xml", "Host":"httpbin.org", "User-Agent":"curl/7.58.0" }, "json":null, "origin":"10.1.1.1, 104.154.179.1", "url":"http://httpbin.org/post" }
Untuk memverifikasi bahwa validasi XSD Anda berfungsi, coba sisipkan tag lain ke dalam isi permintaan Anda. Contoh:
curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock -d '<note> <to>Fred Rogers</to> <from>Nick Danger</from> <heading>Greetings from my neighborhood</heading> <body>Just writing to say hello.</body> <badTag>Not good</badTag> </note>'
Anda akan menerima error validasi.
2: Validasi SOAP
Anda dapat menggunakan kebijakan Validasi Pesan untuk memvalidasi payload permintaan pesan SOAP terhadap WSDL.
- Buat file resource WSDL baru. Misalnya, "example-wsdl.wsdl":
- Tambahkan kebijakan Validasi Pesan SOAP ke pra-alur endpoint proxy Anda:
- Tetapkan atribut
version
elemen<SOAPMessage>
ke versi protokol SOAP yang ingin Anda validasi. Misalnya, "1.1":... <SOAPMessage version="1.1"/> ...
- Tetapkan nilai elemen
<Element>
ke elemen yang ingin Anda validasi:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
menentukan turunan pertama di bawah elemen<Body>
dalam amplop permintaan SOAP.Tetapkan atribut
namespace
ke namespace untuk turunan tersebut. - Tentukan lokasi file resource WSDL Anda dengan elemen
<ResourceURL>
. Contoh:... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
Definisi kebijakan Anda akan terlihat seperti berikut:
<MessageValidation continueOnError="false" enabled="true" name="validateSOAPRequest"> <DisplayName>My SOAP Validator</DisplayName> <Properties/> <Source>request</Source> <SOAPMessage version="1.1"/> <Element namespace="https://example.com/gateway">getID</Element> <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> </MessageValidation>
- Tetapkan atribut
- Kirim permintaan
POST
ke proxy API Anda dengan amplop SOAP sebagai payload pesan, seperti yang ditunjukkan contoh berikut:curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types"> <soapenv:Header/> <soapenv:Body> <prox:getID> <typ:MyType> <typ:ID>42</typ:ID> </typ:MyType> </prox:getID> </soapenv:Body> </soapenv:Envelope>'
Perhatikan bahwa header
Content-type
ditetapkan ke "application/xml".Anda juga dapat membuat file data untuk payload tersebut dan mereferensikannya dengan perintah seperti berikut:
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/soap-payload.xml'
Anda akan menerima respons HTTP 200
. Bergantung pada endpoint target Anda, Anda mungkin menerima detail tambahan tentang permintaan tersebut. Misalnya, jika Anda menggunakan
http://httpbin.org/post
sebagai endpoint target, responsnya harus serupa
dengan berikut:
< HTTP/1.1 200 OK < Date: Wed, 16 May 2018 21:24:54 GMT < Content-Type: application/xml < Content-Length: 431 < Connection: keep-alive < Server: gunicorn/19.8.1 < Access-Control-Allow-Origin: * < Access-Control-Allow-Credentials: true < Via: 1.1 vegur { "args":{}, "data":"<note><to>fred</to><from>nick</from><heading>hello</heading> <body>Just writing to say hello.</body></note>", "files":{}, "form":{}, "headers": { "Accept":"*/*", "Connection":"close", "Content-Length":"106", "Content-Type":"application/xml", "Host":"httpbin.org", "User-Agent":"curl/7.58.0" }, "json":null, "origin":"10.1.1.1, 104.154.179.1", "url":"http://httpbin.org/post" }
3: XML/JSON yang tersusun dengan baik
Anda dapat menggunakan kebijakan Validasi Pesan untuk mengonfirmasi bahwa payload pesan JSON atau XML tersusun dengan baik (tidak sama dengan validasi). Kebijakan ini memastikan struktur dan konten memenuhi standar yang diterima, termasuk:
- Ada satu elemen {i>root<i}
- Tidak ada karakter ilegal dalam konten tersebut
- Objek dan tag disusun bertingkat dengan benar
- Kecocokan tag awal dan akhir
Untuk memeriksa payload XML atau JSON yang tersusun dengan baik:
- Tambahkan kebijakan Validasi Pesan SOAP ke pra-alur endpoint proxy Anda.
- Hapus elemen
<ResourceURL>
,<SOAPMessage>
, dan<Element>
dari definisi kebijakan.Definisi kebijakan Anda akan terlihat seperti berikut:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- Kirim permintaan
POST
ke proxy API Anda, seperti yang ditunjukkan contoh berikut:curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock -d '{ "note": { "to": "Fred Rogers", "from": "Nick Danger", "header": "Greetings from my neighborhood", "body": "Just writing to say hello." } }'
Perhatikan bahwa header
Content-type
disetel keapplication/json
.Untuk memeriksa format yang baik pada file XML, gunakan XML sebagai payload pesan dan tetapkan
Content-type
keapplication/xml
.
Anda akan menerima respons HTTP 200
. Saat Anda mengirim payload pesan
yang tidak berisi XML atau JSON yang tersusun dengan baik, Anda akan menerima
error steps.messagevalidation.Failed
.
Referensi elemen turunan
Bagian ini menjelaskan elemen turunan <MessageValidation>
.
<DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama yang berbeda dan lebih alami.
Elemen <DisplayName>
bersifat umum untuk semua kebijakan.
Nilai Default | T/A |
Wajib? | Opsional. Jika Anda menghilangkan <DisplayName> , nilai
atribut name kebijakan akan digunakan. |
Jenis | String |
Elemen Induk | <PolicyElement> |
Elemen Turunan | Tidak ada |
Elemen <DisplayName>
menggunakan sintaksis berikut:
Sintaksis
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Contoh
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
Elemen <DisplayName>
tidak memiliki atribut atau elemen turunan.
<Element>
Menentukan elemen dalam pesan yang akan divalidasi. Ini adalah turunan pertama dalam elemen <Body>
dalam amplop permintaan SOAP.
Nilai Default | sampleObject |
Wajib? | Opsional |
Type | String |
Elemen Induk |
<MessageValidation>
|
Elemen Turunan | Tidak ada |
Elemen <Element>
menggunakan sintaksis berikut:
Sintaksis
... <Element namespace="element_namespace">element_to_validate</Element> ...
Contoh 1
Contoh berikut menentukan satu elemen yang akan divalidasi:
... <Element namespace="https://example.com/gateway">getID</Element> ...
Contoh 2
Anda dapat menetapkan lebih dari satu elemen untuk divalidasi dengan menambahkan beberapa elemen <Element>
:
... <Element namespace="https://example.com/gateway">getID</Element> <Element namespace="https://example.com/gateway">getDetails</Element> ...
Elemen <Element>
memiliki atribut berikut:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
namespace |
"http://sample.com" | Opsional | Menentukan namespace elemen yang akan divalidasi. |
<ResourceURL>
Mengidentifikasi skema XSD atau definisi WSDL yang akan digunakan untuk memvalidasi pesan sumber.
Nilai Default | wsdl://display_name.wsdl |
Wajib? | Opsional |
Type | String |
Elemen Induk |
<MessageValidation>
|
Elemen Turunan | Tidak ada |
Elemen <ResourceURL>
menggunakan sintaksis berikut:
Sintaksis
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Contoh
Untuk file XML:
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
Untuk WSDL:
... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
Nilai <ResourceURL>
harus mengarah ke file
resource di proxy API Anda. URL tidak boleh merujuk ke resource eksternal melalui HTTP atau HTTPS.
Jika Anda tidak menentukan nilai untuk <ResourceURL>
, pesan akan diperiksa untuk mengetahui JSON atau XML yang tersusun dengan baik jika header Content-type
-nya adalah application/json
atau application/xml
.
Elemen <ResourceURL>
tidak memiliki elemen atau atribut turunan.
Menggunakan XSD untuk validasi
Jika payload XML yang Anda validasi dengan kebijakan MessageValidation merujuk
skema lain, Anda harus mengawali file XSD yang disertakan dengan xsd
dalam
atribut schemaLocation
.
Skema contoh berikut terdiri dari beberapa XSD:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:include schemaLocation="xsd://note-schema.xsd"/> <xs:include schemaLocation="xsd://letter-schema.xsd"/> <xs:include schemaLocation="xsd://user-schema.xsd"/> </xs:schema>
Menggunakan WSDL untuk validasi
WSDL harus menentukan setidaknya satu skema. Jika tidak merujuk ke setidaknya satu skema, kebijakan MessageValidation akan gagal.
Kedalaman impor maksimum untuk skema adalah 10. Jika Anda melebihi jumlah impor bertingkat tersebut, kebijakan MessageValidation akan gagal.
<SOAPMessage>
Menentukan versi SOAP yang divalidasi oleh kebijakan MessageValidation.
Nilai Default | t/a |
Wajib? | Opsional |
Type | t/a |
Elemen Induk |
<MessageValidation>
|
Elemen Turunan | Tidak ada |
Elemen <SOAPMessage>
menggunakan sintaksis berikut:
Sintaksis
... <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/> ...
Contoh
... <SOAPMessage version="1.1"/> ...
Elemen <SOAPMessage>
memiliki atribut berikut:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
version |
Tidak ada | Opsional | Versi SOAP yang digunakan kebijakan ini untuk memvalidasi pesan SOAP.
Nilai yang valid adalah:
|
Untuk informasi selengkapnya, lihat Dari SOAP/1.1 ke SOAP Versi 1.2 dalam 9 poin.
<Source>
Mengidentifikasi pesan sumber yang akan divalidasi. Nilai elemen ini adalah nama pesan yang ingin Anda validasi.
Jika <Source>
tidak disetel, kebijakan ini akan ditetapkan secara default ke message
, yang mengacu pada pesan permintaan lengkap (dalam alur permintaan) atau pesan respons (dalam alur respons), termasuk payload apa pun. Anda juga dapat menetapkannya secara eksplisit ke request
atau response
untuk merujuk pada permintaan atau respons.
Nilai Default | permintaan |
Wajib? | Opsional |
Type | String |
Elemen Induk |
<MessageValidation>
|
Elemen Turunan | Tidak ada |
Elemen <Source>
menggunakan sintaksis berikut:
Sintaksis
... <Source>message_to_validate</Source> ...
Contoh
... <Source>request</Source> ...
Selain message
, request
, dan response
, Anda dapat menetapkan nilai <Source>
ke nama pesan apa pun dalam flow. Namun, jika melakukannya, Anda harus membuat pesan kustom dengan nama tersebut dalam flow sebelum kebijakan ini dieksekusi. Jika tidak, Anda akan menerima pesan error.
Jika nilai <Source>
tidak dapat diselesaikan dalam alur pesan atau di-resolve menjadi jenis non-pesan, salah satu hal berikut akan terjadi:
- Jika nilai null: Apigee akan menampilkan error
steps.messagevalidation.SourceMessageNotAvailable
. - Jika jenis non-pesan: Apigee akan menampilkan error
steps.messagevalidation.NonMessageVariable
.
Elemen <Source>
tidak memiliki atribut atau elemen turunan.
Kode 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 Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Penyebab | Perbaikan |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
Error ini terjadi jika variabel yang ditentukan dalam elemen
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Error ini terjadi jika elemen Variabel jenis pesan mewakili keseluruhan permintaan dan respons HTTP. Variabel alur Apigee bawaan |
build |
steps.messagevalidation.Failed |
500 | Error ini terjadi jika kebijakan SOAPMessageValidation gagal memvalidasi payload pesan input terhadap skema XSD atau definisi WSDL. Hal ini juga akan terjadi jika ada format JSON atau XML dalam pesan payload dengan format yang salah. | build |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaikan |
---|---|---|
InvalidResourceType |
Elemen <ResourceURL> dalam kebijakan SOAPMessageValidation disetel ke jenis resource
yang tidak didukung oleh kebijakan tersebut.
|
build |
ResourceCompileFailed |
Skrip resource yang direferensikan dalam elemen <ResourceURL> kebijakan SOAPMessageValidation berisi error yang mencegah kompilasinya.
|
build |
RootElementNameUnspecified |
Elemen <Element> dalam kebijakan SOAPMessageValidation tidak berisi nama elemen root. |
build |
InvalidRootElementName |
Elemen <Element> dalam kebijakan SOAPMessageValidation berisi nama elemen root yang tidak mematuhi aturan XML untuk penamaan elemen yang valid. |
build |
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd
). Untuk referensi, skema kebijakan tersedia di GitHub.
Topik terkait
- Kebijakan XML Threat Protection
- Kebijakan XML ke JSON
- Kebijakan JSON ke XML
- Kebijakan Perlindungan Ancaman JSON