Kebijakan SOAPMessageValidation

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

Kebijakan SOAPMessageValidation melakukan hal berikut:

  • Memvalidasi setiap pesan XML terhadap skema XSD-nya
  • Memvalidasi pesan SOAP berdasarkan definisi WSDL
  • Menentukan pesan JSON dan XML yang tersusun dengan baik

Meskipun nama kebijakan ini di UI adalah "Validasi Pesan SOAP", kebijakan tersebut memvalidasi lebih banyak lebih dari sekedar pesan SOAP. Bagian ini mengacu pada kebijakan tersebut sebagai "Kebijakan Validasi Pesan".

Elemen <MessageValidation>

Menentukan kebijakan Validasi Pesan.

Nilai Default Lihat tab Kebijakan Default, di bawah
Wajib? Opsional
Jenis 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 Validasi Pesan ke alur Anda di UI Edge:

<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 name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

continueOnError false Opsional Tetapkan ke "false" untuk menampilkan error saat kebijakan gagal. Hal ini wajar untuk sebagian besar kebijakan. Tetapkan ke "true" agar eksekusi flow berlanjut meskipun kebijakan gagal.
enabled benar Opsional Tetapkan ke "true" untuk menerapkan kebijakan. Tetapkan ke "false" untuk "menonaktifkan" kebijakan. Kebijakan ini tidak akan diterapkan meskipun tetap dilampirkan ke flow.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Contoh

Contoh berikut menunjukkan beberapa cara menggunakan Message Validation kebijakan:

1: Validasi XSD

Anda dapat menggunakan kebijakan Validasi Pesan untuk memvalidasi payload permintaan pesan XML dengan skema XSD.

  1. Buat file resource XSD baru. Sebagai misalnya, "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>
  2. Tambahkan kebijakan SOAP Message Validation ke pra-alur endpoint proxy Anda:
    1. Menentukan lokasi file resource XSD dengan <ResourceURL> . Contoh:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Hapus elemen <SOAPMessage> dan <Element> dari definisi kebijakan.

    Definisi kebijakan 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>
  3. Kirim permintaan POST ke proxy API dengan XML sebagai pesan payload Anda, seperti yang ditunjukkan dalam 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 ke "application/xml".

    Anda juga dapat membuat file data untuk payload dan mereferensikannya dengan perintah mirip dengan contoh berikut ini:

    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 titik akhir target, Anda mungkin menerima detail tambahan tentang permintaan tersebut. Misalnya, jika Anda menggunakan http://httpbin.org/post sebagai endpoint target Anda dan tentukan -v (verbose), responsnya harus mirip 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 terhadap 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.

  1. Buat file resource WSDL baru. Misalnya, "example-wsdl.wsdl":
  2. Tambahkan kebijakan SOAP Message Validation ke pra-alur endpoint proxy Anda:
    1. Setel atribut version elemen <SOAPMessage> ke elemen versi protokol SOAP yang ingin Anda validasi. Misalnya, "1,1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. Tetapkan nilai elemen <Element> ke elemen yang ingin Anda validasi:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element> menentukan turunan pertama pada elemen <Body> dalam amplop permintaan SOAP.

      Tetapkan atribut namespace ke namespace untuk turunan tersebut.

    3. Menentukan lokasi file resource WSDL Anda dengan <ResourceURL> . Contoh:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    Definisi kebijakan 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>
  3. Kirim permintaan POST ke proxy API Anda dengan amplop SOAP sebagai payload pesan, seperti yang ditunjukkan dalam 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 disetel ke "application/xml".

    Anda juga dapat membuat file data untuk payload dan mereferensikannya dengan perintah mirip dengan contoh berikut ini:

    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 titik akhir target, Anda mungkin menerima detail tambahan tentang permintaan tersebut. Misalnya, jika Anda menggunakan http://httpbin.org/post sebagai endpoint target Anda, responsnya harus serupa menjadi sebagai 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 diformat 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 bahwa struktur dan konten memenuhi standar yang diterima, termasuk:

  • Ada satu elemen root
  • Tidak ada karakter terlarang dalam konten
  • Objek dan tag disusun bertingkat dengan benar
  • Tag awal dan akhir cocok

Untuk memeriksa payload XML atau JSON yang diformat dengan baik:

  1. Tambahkan kebijakan SOAP Message Validation ke pra-alur endpoint proxy Anda.
  2. Hapus <ResourceURL>, <SOAPMessage>, dan <Element> dari definisi kebijakan.

    Definisi kebijakan akan terlihat seperti berikut:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. Kirim permintaan POST ke proxy API Anda, seperti yang ditampilkan dalam 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 ke "application/json".

    Untuk memeriksa apakah file XML sudah benar, gunakan XML sebagai payload pesan dan setel Content-type ke "application/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 steps.messagevalidation.Failed error.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan dari <MessageValidation>.

<DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di baru dengan nama yang berbeda dan terdengar lebih alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default t/a
Wajib? Opsional. Jika Anda menghapus <DisplayName>, nilai atribut atribut name kebijakan digunakan
Jenis String
Elemen Induk &lt;PolicyElement&gt;
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 anak pertama dari Elemen <Body> dalam amplop permintaan SOAP.

Nilai Default sampleObject
Wajib? Opsional
Jenis 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 menentukan lebih dari satu elemen yang akan divalidasi dengan menambahkan beberapa <Element> elemen:

...
<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 &quot;http://sample.com&quot; 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
Jenis 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 resource file 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 JSON yang diformat dengan baik atau XML jika header Content-type adalah "application/json" atau "application/xml", secara berurutan.

Elemen <ResourceURL> tidak memiliki elemen atau atribut turunan.

Menggunakan XSD untuk validasi

Jika payload XML yang Anda validasi dengan kebijakan Validasi Pesan merujuk skema lain, Anda harus memberikan awalan xsd ke file XSD yang disertakan di bagian Atribut schemaLocation.

Contoh skema 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 mendefinisikan setidaknya satu skema. Jika tidak mereferensikan setidaknya satu skema, Kebijakan Validasi Pesan gagal.

Kedalaman impor maksimum untuk skema adalah 10. Jika Anda melebihi jumlah impor bertingkat tersebut, Kebijakan Validasi Pesan gagal.

<SOAPMessage>

Menentukan versi SOAP yang divalidasi oleh kebijakan Validasi Pesan.

Nilai Default t/a
Wajib? Opsional
Jenis 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:

  • "1,1"
  • "1,2"
  • "1,1/1,2"

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 elemen yang ingin Anda validasi.

Jika Anda tidak menyetel <Source>, kebijakan ini akan ditetapkan secara default ke "message", yang mengacu pada pesan permintaan (dalam alur permintaan) atau pesan respons (dalam alur respons), termasuk setiap payload. Anda juga dapat secara eksplisit menetapkannya ke "{i>request<i}" atau "respons" untuk merujuk ke permintaan atau yang dihasilkan.

Nilai Default minta
Wajib? Opsional
Jenis 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 alur Anda. Namun, jika Anda melakukan ini, Anda harus membuat dengan nama tersebut di alur Anda sebelum kebijakan ini dijalankan. Jika tidak, Anda akan mendapatkan mengalami {i>error.<i}

Jika nilai <Source> tidak dapat diselesaikan dalam alur pesan atau di-resolve menjadi bukan pesan , maka salah satu hal berikut akan terjadi:

  • Jika nilai null: Edge akan menampilkan Error steps.messagevalidation.SourceMessageNotAvailable.
  • Jika jenis non-pesan: Edge menampilkan Error steps.messagevalidation.NonMessageVariable.

Elemen <Source> tidak memiliki atribut atau elemen turunan.

Kode error

Error yang ditampilkan dari kebijakan Edge mengikuti format yang konsisten seperti yang dijelaskan dalam Referensi kode error.

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan 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 Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaiki
steps.messagevalidation.SourceMessageNotAvailable 500

Error ini terjadi jika variabel yang ditentukan dalam elemen <Source> kebijakan:

  • di luar cakupan (tidak tersedia di alur spesifik tempat kebijakan sedang dijalankan)
  • atau
  • tidak dapat diselesaikan (tidak ditentukan)
steps.messagevalidation.NonMessageVariable 500

Error ini terjadi jika elemen <Source> dalam kebijakan SOAPMessageValidation disetel ke variabel yang bukan jenis pesan.

Variabel jenis pesan mewakili keseluruhan permintaan dan respons HTTP. Variabel alur Edge bawaan request, response, dan message adalah jenis pesan. Untuk mempelajari variabel pesan lebih lanjut, baca Referensi variabel.

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.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab Perbaiki
InvalidResourceType Elemen <ResourceURL> dalam kebijakan SOAPMessageValidation disetel ke jenis resource yang tidak didukung oleh kebijakan tersebut.
ResourceCompileFailed Skrip resource yang direferensikan dalam elemen <ResourceURL> kebijakan SOAPMessageValidation berisi error yang mencegah kompilasinya.
RootElementNameUnspecified Elemen <Element> dalam kebijakan SOAPMessageValidation tidak berisi nama elemen root.
InvalidRootElementName Elemen <Element> dalam kebijakan SOAPMessageValidation berisi nama elemen root yang tidak mematuhi aturan XML untuk penamaan elemen yang valid.

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Topik terkait