Zasada SOAPMessageValidation

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Zasada SOAPMessageValidation wykonuje te działania:

  • Sprawdza każdą wiadomość XML pod kątem ich schematów XSD
  • Sprawdza poprawność komunikatów SOAP pod kątem definicji WSDL
  • Określa poprawność formatu komunikatów JSON i XML
.

Nazwa tej zasady w interfejsie to „SOAP Message Validation”, ale zasada weryfikuje więcej niż tylko komunikaty SOAP. Ta sekcja określa zasady jako „Zasady weryfikacji wiadomości”.

<MessageValidation> element

Definiuje zasadę weryfikacji wiadomości.

Wartość domyślna Zobacz kartę Zasady domyślne poniżej
Wymagany? Opcjonalnie
Typ Złożony obiekt
Element nadrzędny nie dotyczy
Elementy podrzędne <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

Składnia

Element <MessageValidation> ma taką składnię:

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

Domyślna zasada

Poniższy przykład pokazuje ustawienia domyślne, gdy dodajesz zasadę weryfikacji wiadomości. do procesu w interfejsie 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>

Ten element ma te atrybuty, które są wspólne dla wszystkich zasad:

Atrybut Domyślnie Wymagany? Description
name Nie dotyczy Wymagane

Wewnętrzna nazwa zasady. Wartość atrybutu name może zawierać litery, cyfry, spacje, łączniki, podkreślenia i kropki. Ta wartość nie może przekraczać 255 znaków.

Opcjonalnie użyj elementu <DisplayName>, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną nazwą w języku naturalnym.
continueOnError fałsz Opcjonalnie Ustaw wartość „false”, aby wyświetlać błąd, gdy zasada nie działa. To prawidłowy proces w przypadku większości zasad. Ustaw wartość „true”, aby kontynuować wykonywanie przepływu nawet po wystąpieniu błędu.
enabled prawda Opcjonalnie Ustaw wartość „true”, aby egzekwować zasadę. Ustaw wartość „false”, aby wyłączyć zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie powiązana z przepływem.
async   fałsz Wycofano Ten atrybut został wycofany.

Przykłady

Poniższe przykłady pokazują niektóre sposoby korzystania z funkcji walidacji wiadomości. zasady:

1. Weryfikacja XSD

Za pomocą zasady walidacji wiadomości możesz zweryfikować ładunek żądania wiadomości XML ze schematem XSD.

  1. Utwórz nowy plik zasobów XSD. Dla: na przykład „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. Dodaj zasadę weryfikacji komunikatów SOAP do procesu wstępnego sprawdzania punktu końcowego serwera proxy:
    1. <ResourceURL> pozwala określić lokalizację pliku zasobów XSD . Na przykład: 
      ...
  <ResourceURL>xsd://note-schema.xsd</ResourceURL>
...
    2. Usuń elementy <SOAPMessage> i <Element> z definicji zasad.

    Definicja zasady powinna wyglądać tak:

    <MessageValidation continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My XML Validator</DisplayName>
  <Properties/>
  <Source>request</Source>
  <ResourceURL>xsd://note-schema.xsd</ResourceURL>
</MessageValidation>
  3. Wyślij żądanie POST do serwera proxy interfejsu API z kodem XML jako komunikatem. ładunek, jak w tym przykładzie: 
    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>'

    Zwróć uwagę, że nagłówek Content-type jest ustawiony na „application/xml”.

    Możesz też utworzyć plik danych dla ładunku i odwołać się do niego za pomocą polecenia podobnie jak poniżej:

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

Otrzymasz odpowiedź HTTP 200. W zależności od docelowego punktu końcowego możesz otrzymać dodatkowe informacje o tej prośbie. Na przykład, jeśli używasz http://httpbin.org/post jako docelowy punkt końcowy i określ -v (wyczerpująco), odpowiedź powinna być podobna do tej:

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

Aby sprawdzić, czy weryfikacja XSD działa, spróbuj wstawić inny tag do treści na Twoją prośbę. Na przykład:

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

Powinien pojawić się błąd weryfikacji.

2. Weryfikacja SOAP

Za pomocą zasady walidacji wiadomości możesz zweryfikować ładunek żądania komunikatu SOAP wobec WSDL.

  1. Utwórz nowy plik zasobów WSDL. Na przykład „example-wsdl.wsdl”:
  2. Dodaj zasadę weryfikacji komunikatów SOAP do procesu wstępnego sprawdzania punktu końcowego serwera proxy:
    1. Ustaw atrybut version elementu <SOAPMessage> na wersji protokołu SOAP, w której chcesz sprawdzić poprawność. Przykład: „1.1”: 
      ...
  <SOAPMessage version="1.1"/>
...
    2. Ustaw wartość elementu <Element> jako elementu, który chcesz ustawić. weryfikuj: 
      ...
  <Element namespace="https://example.com/gateway">getID</Element>
...

      <Element> określa pierwszy element podrzędny w elemencie <Body> w kopercie żądania SOAP.

      Ustaw atrybut namespace na przestrzeń nazw tego elementu podrzędnego.

    3. <ResourceURL> pozwala określić lokalizację pliku zasobów WSDL . Na przykład: 
      ...
  <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

    Definicja zasady powinna wyglądać tak:

    <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. Wyślij żądanie POST do serwera proxy interfejsu API z kopertą SOAP jako ładunek wiadomości, jak w tym przykładzie: 
    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>'

    Zwróć uwagę, że nagłówek Content-type jest ustawiony na „application/xml”.

    Możesz też utworzyć plik danych dla ładunku i odwołać się do niego za pomocą polecenia podobnie jak poniżej:

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

Otrzymasz odpowiedź HTTP 200. W zależności od docelowego punktu końcowego możesz otrzymać dodatkowe informacje o tej prośbie. Na przykład, jeśli używasz http://httpbin.org/post jako docelowy punkt końcowy, odpowiedź powinna być podobna na:

< 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. Prawidłowy format XML/JSON

Za pomocą zasady walidacji wiadomości możesz potwierdzić, że ładunek wiadomości w formacie JSON lub XML jest prawidłowo sformułowany (to nie to samo co weryfikacja). Zasada zapewnia, że struktura oraz treści spełniają przyjęte standardy, takie jak:

  • Występuje jeden pierwiastek
  • treść nie zawiera niedozwolonych znaków,
  • Obiekty i tagi są prawidłowo zagnieżdżone
  • Jednakowe tagi początkowe i końcowe

Aby sprawdzić poprawność formatu ładunku XML lub JSON:

  1. Dodaj zasadę weryfikacji wiadomości SOAP do procesu wstępnego sprawdzania punktu końcowego serwera proxy.
  2. Usuń <ResourceURL>, <SOAPMessage>, i <Element> z definicji zasady.

    Definicja zasady powinna wyglądać tak:

    <MessageValidation async="false" continueOnError="false"
    enabled="true" name="validateXMLRequest">
  <DisplayName>My JSON Checker</DisplayName>
  <Properties/>
  <Source>request</Source>
</MessageValidation>
  3. Wyślij żądanie POST do serwera proxy interfejsu API, jak w tym przykładzie: 
    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."
  }
}'

    Zwróć uwagę, że nagłówek Content-type ma wartość „application/json”.

    Aby sprawdzić poprawność pliku XML, użyj formatu XML jako ładunku wiadomości i ustaw Content-type na „application/xml”.

Otrzymasz odpowiedź HTTP 200. Gdy wysyłasz ładunek wiadomości który nie zawiera poprawnie sformatowanego kodu XML lub JSON, powinien zostać zwrócony błąd steps.messagevalidation.Failed błąd.

Odniesienie do elementu podrzędnego

W tej sekcji opisano elementy podrzędne elementu <MessageValidation>.

<DisplayName>

Używaj oprócz atrybutu name do oznaczania zasady w edytor serwera proxy w interfejsie zarządzania o innej, bardziej naturalnie brzmiącej nazwie.

Element <DisplayName> jest wspólny dla wszystkich zasad.

Wartość domyślna nie dotyczy
Wymagany? Opcjonalnie: Jeśli pominiesz <DisplayName>, wartość pary klucz-wartość jest używany atrybut name zasady
Typ Ciąg znaków
Element nadrzędny &lt;PolicyElement&gt;
Elementy podrzędne Brak

Element <DisplayName> ma taką składnię:

Składnia

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

Przykład

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

Element <DisplayName> nie ma atrybutów ani elementów podrzędnych.

<Element>

Określa element wiadomości do sprawdzenia. To jest pierwsze dziecko poniżej <Body> element w kopercie żądania SOAP.

Wartość domyślna sampleObject
Wymagany? Opcjonalnie
Typ Ciąg znaków
Element nadrzędny <MessageValidation>
Elementy podrzędne Brak

Element <Element> ma taką składnię:

Składnia

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

Przykład 1

Ten przykład wskazuje 1 element do zweryfikowania:

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

Przykład 2

Możesz określić więcej niż 1 element do zweryfikowania, dodając kilka elementów <Element> elementy:

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

Element <Element> ma te atrybuty:

Atrybut Domyślny Wymagana? Opis
namespace &quot;http://sample.com&quot; Opcjonalnie Określa przestrzeń nazw elementu do zweryfikowania.

<ResourceURL>

Określa schemat XSD lub definicję WSDL używaną do weryfikacji komunikatu źródłowego.

Wartość domyślna wsdl://display_name.wsdl
Wymagany? Opcjonalnie
Typ Ciąg znaków
Element nadrzędny <MessageValidation>
Elementy podrzędne Brak

Element <ResourceURL> ma taką składnię:

Składnia

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

Przykłady

W przypadku pliku XML:

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

W przypadku WSDL:

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

Wartość <ResourceURL> musi wskazywać zasób w serwerze proxy interfejsu API. Nie może odnosić się do zasobów zewnętrznych przez HTTP ani HTTPS.

Jeśli nie określisz wartości w polu <ResourceURL>, wiadomość będzie sprawdzana pod kątem poprawności formatu JSON. lub XML, jeśli nagłówek Content-type to „application/json” lub „application/xml”, .

Element <ResourceURL> nie ma elementów podrzędnych ani atrybutów.

Używanie plików XSD do walidacji

Jeśli ładunek XML weryfikowany przez Ciebie za pomocą odniesień do zasady weryfikacji wiadomości inny schemat, musisz poprzedzić dołączony plik XSD prefiksem xsd w schemaLocation.

Ten przykładowy schemat składa się z wielu plików 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>

Używanie WSDL do weryfikacji

WSDL musi definiować co najmniej 1 schemat. Jeśli nie odwołuje się do co najmniej jednego schematu, definicja Zasada weryfikacji wiadomości kończy się niepowodzeniem.

Maksymalna głębokość importu dla schematu to 10. Jeśli przekroczysz tę liczbę zagnieżdżonych importów, Zasada weryfikacji wiadomości kończy się niepowodzeniem.

<SOAPMessage>

Definiuje wersję SOAP, z którą jest weryfikowana zasada walidacji wiadomości.

Wartość domyślna nie dotyczy
Wymagany? Opcjonalnie
Typ nie dotyczy
Element nadrzędny <MessageValidation>
Elementy podrzędne Brak

Element <SOAPMessage> ma taką składnię:

Składnia

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

Przykład

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

Element <SOAPMessage> ma te atrybuty:

Atrybut Domyślny Wymagana? Opis
version Brak Opcjonalnie Wersja SOAP używana przez tę zasadę do weryfikacji komunikatów SOAP.

Prawidłowe wartości to:

  • „1.1”
  • „1,2”
  • „1.1/1,2”

Więcej informacji: Z SOAP/1.1 do SOAP Wersja 1.2 w 9 punktach.

<Source>

Identyfikuje komunikat źródłowy do zweryfikowania. Wartość tego elementu to nazwa elementu wiadomość, którą chcesz sprawdzić.

Jeśli nie skonfigurujesz zasady <Source>, domyślnie zostanie użyta wartość „wiadomość”, która odnosi się do kompletnego z żądaniem (w ramach procesu żądania) lub wiadomości z odpowiedzią (w ramach procesu odpowiedzi), w tym: ładunek. Możesz też wprost wybrać dla niego wartość „request”. lub „odpowiedź” lub odwołać się do prośby .

Wartość domyślna żądanie
Wymagany? Opcjonalnie
Typ Ciąg znaków
Element nadrzędny <MessageValidation>
Elementy podrzędne Brak

Element <Source> ma taką składnię:

Składnia

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

Przykład

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

Oprócz opcji „wiadomość”, „żądanie” i „odpowiedź” możesz ustawić wartość <Source> do nazwy dowolnej wiadomości w przepływie. Jeśli to zrobisz, musisz utworzyć komunikat niestandardowy o tej nazwie w przepływie przed wykonaniem tej zasady. W przeciwnym razie otrzymasz błąd.

Jeśli wartości <Source> nie można znaleźć w przepływie wiadomości lub przekształca się w wartość inną niż wiadomość , zachodzi jedna z tych sytuacji:

  • Jeśli wartość to null: krawędź zgłasza steps.messagevalidation.SourceMessageNotAvailable błąd.
  • Jeśli typ inny niż wiadomość: Edge przesyła steps.messagevalidation.NonMessageVariable błąd.

Element <Source> nie ma atrybutów ani elementów podrzędnych.

Kody błędów

Błędy zwracane przez zasady Edge mają spójny format opisany w dokumentacji kodu błędów.

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Kod błędu Stan HTTP Przyczyna Napraw
steps.messagevalidation.SourceMessageNotAvailable 500

Ten błąd występuje, jeśli zmienna określona w elemencie <Source> zasady ma jedną z tych wartości:

  • poza zakresem (niedostępne w konkretnym procesie, w którym jest wykonywana zasada)
    • lub
  • Nie można rozwiązać (nie określono)
steps.messagevalidation.NonMessageVariable 500

Ten błąd występuje, jeśli element <Source> w zasadzie SOAPMessageValidation jest ustawiony na zmienną, która nie jest typu komunikat.

Zmienne typu wiadomości reprezentują całe żądania i odpowiedzi HTTP. Wbudowane zmienne przepływu Edge request, response i message mają typ komunikatu. Więcej informacji o zmiennych wiadomości znajdziesz w dokumentacji zmiennych.
steps.messagevalidation.Failed 500 Ten błąd występuje, jeśli zasada SOAPMessageValidation nie sprawdza poprawności ładunku wejściowego wiadomości w odniesieniu do schematu XSD lub definicji WSDL. Ten błąd może wystąpić również wtedy, gdy w wiadomości z ładunkiem występuje nieprawidłowy format JSON lub XML.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Nazwa błędu Przyczyna Napraw
InvalidResourceType Element <ResourceURL> w zasadzie SOAPMessageValidation jest ustawiony na typ zasobu, który nie jest obsługiwany przez tę zasadę.
ResourceCompileFailed Skrypt zasobów, do którego odwołuje się element <ResourceURL> zasady SOAPMessageValidation, zawiera błąd uniemożliwiający mu kompilowanie.
RootElementNameUnspecified Element <Element> w zasadzie SOAPMessageValidation nie zawiera nazwy elementu głównego.
InvalidRootElementName Element <Element> w zasadzie SOAPMessageValidation zawiera nazwę elementu głównego, która jest niezgodna z regułami XML dotyczącymi prawidłowych nazw elementów.

Schematy

Każdy typ zasad jest definiowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.

Powiązane artykuły