SOAPMessageVerify politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin.
bilgi

SOAPMessageValidation politikası şunları yapar:

  • Tüm XML mesajlarını XSD şemalarına göre doğrular
  • SOAP mesajlarını bir WSDL tanımına göre doğrular
  • JSON ve XML iletilerinin biçiminin doğru olup olmadığını belirler

Kullanıcı arayüzündeki bu politikanın adı "SOAP Message Validation" olsa da politika, SOAP mesajlarından daha fazlasını doğrular. Bu bölümde söz konusu politika "İleti Doğrulama politikası" olarak adlandırılır.

<MessageValidation> öğe

İleti Doğrulama politikasını tanımlar.

Varsayılan Değer Aşağıdaki Varsayılan Politika sekmesine bakın
Zorunlu mu? İsteğe bağlı
Tür Karmaşık nesne
Üst Öğe Yok
Alt Öğeler <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

Söz dizimi

<MessageValidation> öğesi şu söz dizimini kullanır:

<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>

Varsayılan Politika

Aşağıdaki örnekte, Edge kullanıcı arayüzünde akışınıza Mesaj Doğrulama politikası eklediğinizde varsayılan ayarlar gösterilmektedir:

<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>

Bu öğe, tüm politikalarda ortak olan aşağıdaki özelliklere sahiptir:

Özellik Varsayılan Zorunlu mu? Açıklama
name Yok Zorunlu

Politikanın dahili adı. name özelliğinin değeri harf, sayı, boşluk, kısa çizgi, alt çizgi ve nokta içerebilir. Bu değer 255 karakteri aşamaz.

İsteğe bağlı olarak, politikayı yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı, doğal bir dille etiketlemek için <DisplayName> öğesini kullanın.

continueOnError yanlış İsteğe bağlı Politika başarısız olduğunda hata döndürmek için "false" değerine ayarlayın. Bu, çoğu politika için beklenen bir durumdur. Bir politika başarısız olsa bile akış yürütmenin devam etmesi için değeri "true" olarak ayarlayın.
enabled true İsteğe bağlı Politikayı uygulamak için "true" (doğru) değerine ayarlayın. Politikayı "kapalı" hale getirmek için "false" değerine ayarlayın. Politika, bir akışa bağlı kalsa bile zorunlu kılınmaz.
async   yanlış Kullanımdan kaldırıldı Bu özellik kullanımdan kaldırıldı.

Örnekler

Aşağıdaki örneklerde, Mesaj Doğrulama politikasını kullanabileceğiniz bazı yöntemler gösterilmektedir:

1: XSD Doğrulaması

XML mesajı isteğinin yükünü bir XSD şemasına göre doğrulamak için Message Validation politikasını kullanabilirsiniz.

  1. Yeni bir XSD kaynak dosyası oluşturun. Örneğin, "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. SOAP Mesaj Doğrulama politikasını proxy uç noktanızın ön akışına ekleyin:
    1. XSD kaynak dosyanızın konumunu <ResourceURL> öğesiyle belirtin. Örneğin:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Politika tanımından <SOAPMessage> ve <Element> öğelerini kaldırın.

    Politika tanımınız aşağıdaki gibi görünmelidir:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. Aşağıdaki örnekte gösterildiği gibi, API proxy'nize mesaj yükü olarak XML'inizle bir POST isteği gönderin:
    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>'

    Content-type üstbilgisinin "application/xml" olarak ayarlandığına dikkat edin.

    Ayrıca yük için bir veri dosyası oluşturup aşağıdakine benzer bir komutla bu dosyayı referans alabilirsiniz:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

HTTP 200 yanıtı alırsınız. Hedef uç noktanıza bağlı olarak istek hakkında ek bilgiler alabilirsiniz. Örneğin, hedef uç noktanız olarak http://httpbin.org/post kullanıyorsanız ve -v (ayrıntılı) çıkışını belirtirseniz yanıt aşağıdakine benzer olacaktır:

< 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"
}

XSD doğrulamanızın çalıştığını doğrulamak için isteğinizin gövdesine başka bir etiket eklemeyi deneyin. Örneğin:

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>'

Doğrulama hatası alırsınız.

2: SOAP Doğrulaması

SOAP mesaj isteğinin yükünü WSDL ile doğrulamak için Mesaj Doğrulama politikasını kullanabilirsiniz.

  1. Yeni bir WSDL kaynak dosyası oluşturun. Örneğin, "example-wsdl.wsdl":
  2. SOAP Mesaj Doğrulama politikasını proxy uç noktanızın ön akışına ekleyin:
    1. <SOAPMessage> öğesinin version özelliğini, doğrulama yapmak istediğiniz SOAP protokolünün sürümüne ayarlayın. Örneğin, "1.1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. <Element> öğesinin değerini, doğrulamak istediğiniz öğeye ayarlayın:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element>, SOAP isteğinin zarfındaki <Body> öğesi altındaki ilk alt öğeyi belirtir.

      namespace özelliğini söz konusu alt öğenin ad alanına ayarlayın.

    3. WSDL kaynak dosyanızın konumunu <ResourceURL> öğesiyle belirtin. Örneğin:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    Politika tanımınız aşağıdaki gibi görünmelidir:

    <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. Aşağıdaki örnekte gösterildiği gibi, API proxy'nize mesaj yükü olarak SOAP zarfıyla bir POST isteği gönderin:
    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>'

    Content-type üstbilgisinin "application/xml" olarak ayarlandığına dikkat edin.

    Ayrıca yük için bir veri dosyası oluşturup aşağıdakine benzer bir komutla bu dosyayı referans alabilirsiniz:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

HTTP 200 yanıtı alırsınız. Hedef uç noktanıza bağlı olarak istek hakkında ek bilgiler alabilirsiniz. Örneğin, hedef uç noktanız olarak http://httpbin.org/post kullanıyorsanız yanıt aşağıdakine benzer olmalıdır:

< 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: İyi biçimlendirilmiş XML/JSON

Bir JSON veya XML mesajı yükünün doğru şekilde biçimlendirildiğini (doğrulama ile aynı değildir) onaylamak için Mesaj Doğrulama politikasını kullanabilirsiniz. Politika, yapının ve içeriğin kabul edilen standartları karşılamasını sağlar. Bu standartlara şunlar dahildir:

  • Tek bir kök öğe vardır
  • İçerikte yasa dışı karakter yok
  • Nesneler ve etiketler düzgün şekilde iç içe yerleştirilmiş
  • Başlangıç ve bitiş etiketleri eşleşiyor

İyi biçimlendirilmiş bir XML veya JSON yükü olup olmadığını kontrol etmek için:

  1. SOAP Mesaj Doğrulama politikasını proxy uç noktanızın ön akışına ekleyin.
  2. <ResourceURL>, <SOAPMessage> ve <Element> öğelerini politika tanımından kaldırın.

    Politika tanımınız aşağıdaki gibi görünmelidir:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. API proxy'nize aşağıdaki örnekte gösterildiği gibi bir POST isteği gönderin:
    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."
      }
    }'

    Content-type üstbilgisinin "application/json" olarak ayarlandığına dikkat edin.

    XML dosyasının iyi biçimlendirilip biçimlendirilmediğini kontrol etmek için mesaj yükü olarak XML kullanın ve Content-type öğesini "application/xml" olarak ayarlayın.

HTTP 200 yanıtı alırsınız. Doğru biçimlendirilmiş XML veya JSON içermeyen bir mesaj yükü gönderdiğinizde steps.messagevalidation.Failed hatası alırsınız.

Alt öğe referansı

Bu bölümde <MessageValidation> alt öğeleri açıklanmaktadır.

<DisplayName>

Politikayı, yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı, daha doğal bir adla etiketlemek için name özelliğine ek olarak kullanın.

<DisplayName> öğesi tüm politikalarda ortaktır.

Varsayılan Değer Yok
Zorunlu mu? İsteğe bağlı. <DisplayName> özelliğini çıkarırsanız politikanın name özelliğinin değeri kullanılır
Tür Dize
Üst Öğe <PolicyElement>
Alt Öğeler Yok

<DisplayName> öğesi şu söz dizimini kullanır:

Söz dizimi

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Örnek

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> öğesinin özelliği veya alt öğesi yoktur.

<Element>

Mesajdaki doğrulanacak öğeyi belirtir. Bu, SOAP isteğinin zarfındaki <Body> öğesinin altındaki ilk alt öğedir.

Varsayılan Değer sampleObject
Zorunlu mu? İsteğe bağlı
Tür Dize
Üst Öğe <MessageValidation>
Alt Öğeler Yok

<Element> öğesi şu söz dizimini kullanır:

Söz dizimi

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

1. Örnek

Aşağıdaki örnekte doğrulanacak tek bir öğe tanımlanmaktadır:

...
<Element namespace="https://example.com/gateway">getID</Element>
...

2. Örnek

Birden fazla <Element> öğesi ekleyerek doğrulanacak birden fazla öğe belirtebilirsiniz:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

<Element> öğesi aşağıdaki özelliklere sahiptir:

Özellik Varsayılan Zorunlu mu? Açıklama
namespace "http://sample.com" İsteğe bağlı Doğrulanacak öğenin ad alanını tanımlar.

<ResourceURL>

Kaynak mesajı doğrulamak için kullanılacak XSD şemasını veya WSDL tanımını tanımlar.

Varsayılan Değer wsdl://display_name.wsdl
Zorunlu mu? İsteğe bağlı
Tür Dize
Üst Öğe <MessageValidation>
Alt Öğeler Yok

<ResourceURL> öğesi şu söz dizimini kullanır:

Söz dizimi

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

Örnekler

XML dosyası için:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

WSDL için:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

<ResourceURL> değeri, API proxy'nizdeki bir kaynak dosyasına işaret etmelidir. HTTP veya HTTPS üzerinden harici kaynaklara başvuramaz.

<ResourceURL> için değer belirtmezseniz Content-type üstbilgisi "application/json" veya "application/xml" ise mesaj iyi biçimlendirilmiş JSON ya da XML için kontrol edilir.

<ResourceURL> öğesinin alt öğesi veya özelliği yoktur.

Doğrulama için XSD'leri kullanma

Message Validation politikasıyla doğruladığınız XML yükü başka bir şemaya referans veriyorsa dahil edilen XSD dosyasının önüne schemaLocation özelliğinde xsd ifadesi eklemeniz gerekir.

Aşağıdaki örnek şema birden çok XSD'den oluşur:

<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>

Doğrulama için WSDL'leri kullanma

WSDL en az bir şema tanımlamalıdır. En az bir şemaya referans vermiyorsa Mesaj Doğrulama politikası başarısız olur.

Bir şema için maksimum içe aktarma derinliği 10'dur. İç içe aktarma işlemlerinin sayısını aşarsanız İleti Doğrulama politikası başarısız olur.

<SOAPMessage>

Mesaj Doğrulama politikasının doğrulanacağı SOAP sürümünü tanımlar.

Varsayılan Değer Yok
Zorunlu mu? İsteğe bağlı
Tür Yok
Üst Öğe <MessageValidation>
Alt Öğeler Yok

<SOAPMessage> öğesi şu söz dizimini kullanır:

Söz dizimi

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

Örnek

...
<SOAPMessage version="1.1"/>
...

<SOAPMessage> öğesi aşağıdaki özelliklere sahiptir:

Özellik Varsayılan Zorunlu mu? Açıklama
version Yok İsteğe bağlı Bu politikanın SOAP mesajlarını doğrulamak için kullandığı SOAP sürümü.

Valid values are:

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

Daha fazla bilgi için SOAP/1.1'den SOAP Sürüm 1.2'ye 9 puanda bakın.

<Source>

Doğrulanacak kaynak mesajı tanımlar. Bu öğenin değeri, doğrulamak istediğiniz mesajın adıdır.

<Source> politikasını ayarlamazsanız bu politika varsayılan olarak "mesaj" değerini alır. Bu, tüm yük dahil olmak üzere tam istek mesajını (istek akışında) veya yanıt mesajını (yanıt akışında) ifade eder. Ayrıca, istek veya yanıta atıfta bulunmak için bunu açıkça "istek" ya da "yanıt" olarak da ayarlayabilirsiniz.

Varsayılan Değer istek
Zorunlu mu? İsteğe bağlı
Tür Dize
Üst Öğe <MessageValidation>
Alt Öğeler Yok

<Source> öğesi şu söz dizimini kullanır:

Söz dizimi

...
  <Source>message_to_validate</Source>
...

Örnek

...
<Source>request</Source>
...

"Mesaj", "istek" ve "yanıt"a ek olarak <Source> değerini, akışınızdaki herhangi bir mesajın adı olarak ayarlayabilirsiniz. Ancak bunu yaparsanız bu politika yürütülmeden önce akışınızda bu adla özel bir mesaj oluşturmanız gerekir. Aksi takdirde hata mesajı alırsınız.

<Source> değeri mesaj akışında çözümlenemezse veya mesaj olmayan bir türe çözülürse aşağıdakilerden biri gerçekleşir:

  • Değer boşsa: Edge steps.messagevalidation.SourceMessageNotAvailable hatası verir.
  • Mesaj türünde olmayan bir türse: Edge steps.messagevalidation.NonMessageVariable hatası verir.

<Source> öğesinin özelliği veya alt öğesi yoktur.

Hata kodları

Edge politikalarından döndürülen hatalar, Hata kodu referansı bölümünde açıklandığı gibi tutarlı bir biçime sahiptir.

Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ile hata mesajları ve döndürülen hata mesajları ile Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiyi, hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.

Çalışma zamanı hataları

Politika yürütüldüğünde bu hatalar ortaya çıkabilir.

Hata kodu HTTP durumu Neden Düzelt
steps.messagevalidation.SourceMessageNotAvailable 500

Bu hata, politikanın <Source> öğesinde belirtilen bir değişken şunlardan biriyse ortaya çıkar:

  • kapsam dışında (politikanın yürütüldüğü belirli akışta kullanılamaz)
  • veya
  • çözülemiyor (tanımlanmadı)
steps.messagevalidation.NonMessageVariable 500

Bu hata, SOAPMessageValidation politikasındaki <Source> öğesi, mesaj türünde olmayan bir değişkene ayarlanırsa ortaya çıkar.

Mesaj türü değişkenleri, HTTP isteklerinin ve yanıtlarının tamamını temsil eder. Yerleşik Edge akış değişkenleri request, response ve message mesaj türündedir. Mesaj değişkenleri hakkında daha fazla bilgi için Değişkenler referansı başlıklı makaleyi inceleyin.

steps.messagevalidation.Failed 500 Bu hata, SOAPMessageValidation politikası, giriş mesajı yükünü XSD şeması veya WSDL tanımına göre doğrulayamazsa ortaya çıkar. Yük mesajında bozuk JSON veya XML bulunması da bu hataya neden olabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Hata adı Neden Düzelt
InvalidResourceType SOAPMessageValidation politikasındaki <ResourceURL> öğesi, politika tarafından desteklenmeyen bir kaynak türüne ayarlanmış.
ResourceCompileFailed SOAPMessageValidation politikasının <ResourceURL> öğesinde başvurulan kaynak komut dosyası, derlemesini engelleyen bir hata içeriyor.
RootElementNameUnspecified SOAPMessageValidation politikasındaki <Element>, kök öğenin adını içermiyor.
InvalidRootElementName SOAPMessageValidation politikasındaki <Element> öğesi, geçerli öğe adlandırmaya yönelik XML kurallarına uymayan bir kök öğe adı içeriyor.

Şemalar

Her politika türü, XML şemasıyla (.xsd) tanımlanır. GitHub'da, politika şemalarını referans olarak bulabilirsiniz.

İlgili konular