Zasada SOAPMessageValidation

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X.
informacje.

Zasada SOAPMessageValidation wykonuje te operacje:

  • Weryfikuje dowolną wiadomość XML w odniesieniu do jej schematów XSD
  • Weryfikuje komunikaty SOAP w oparciu o definicję WSDL
  • Określa prawidłową formę wiadomości JSON i XML

Chociaż nazwa tej zasady w interfejsie to „SOAP Message Verificationation”, zasada weryfikuje więcej niż tylko komunikaty SOAP. W tej sekcji zasady są określane jako „Zasady dotyczące sprawdzania poprawności wiadomości”.

<MessageValidation> element

Definiuje zasadę weryfikacji wiadomości.

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

Składnia

W elemencie <MessageValidation> używana jest taka składnia:

<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 podczas dodawania zasady weryfikacji wiadomości do przepływu w interfejsie użytkownika 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ą sposoby użycia zasad walidacji wiadomości:

1: walidacja XSD

Za pomocą zasady weryfikacji wiadomości możesz zweryfikować ładunek żądania wiadomości XML w odniesieniu do schematu XSD.

  1. Utwórz nowy plik zasobów XSD. 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 wiadomości SOAP do procesu wstępnego w punkcie końcowym serwera proxy:
    1. Określ lokalizację pliku zasobów XSD za pomocą elementu <ResourceURL>. Przykład:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Usuń elementy <SOAPMessage> i <Element> z definicji zasady.

    Definicja zasad 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 ładunku wiadomości, jak pokazano w poniższym 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 podobnego do tego:

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

Powinna wyświetlić się odpowiedź HTTP 200. W zależności od docelowego punktu końcowego możesz otrzymać dodatkowe informacje o żądaniu. Jeśli na przykład używasz http://httpbin.org/post jako punktu końcowego i określisz dane wyjściowe -v (wyczerpujące), 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 żądania. 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 wiadomości SOAP w odniesieniu do WSDL.

  1. Utwórz nowy plik zasobów WSDL. Na przykład „example-wsdl.wsdl”:
  2. Dodaj zasadę weryfikacji wiadomości SOAP do procesu wstępnego w punkcie końcowym serwera proxy:
    1. Ustaw atrybut version elementu <SOAPMessage> na wersję protokołu SOAP, pod kątem której chcesz przeprowadzić weryfikację. Na przykład „1.1”:
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. Ustaw wartość elementu <Element> na element, który chcesz sprawdzić:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

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

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

    3. Określ lokalizację pliku zasobów WSDL za pomocą elementu <ResourceURL>. Przykład:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    Definicja zasad 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 ładunkiem wiadomości, jak pokazano w poniższym 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 podobnego do tego:

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

Powinna wyświetlić się odpowiedź HTTP 200. W zależności od docelowego punktu końcowego możesz otrzymać dodatkowe informacje o żądaniu. Jeśli na przykład używasz http://httpbin.org/post jako docelowego punktu końcowego, 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"
}

3. Kod XML/JSON powinien być poprawnie sformatowany

Za pomocą zasady weryfikacji wiadomości możesz sprawdzić, czy ładunek wiadomości w formacie JSON lub XML jest poprawnie sformatowany (inny niż weryfikacja). Zasady te gwarantują, że struktura i treści będą zgodne z akceptowanymi standardami, takimi jak:

  • Jest jeden element główny
  • treść nie zawiera niedozwolonych znaków,
  • Obiekty i tagi są prawidłowo zagnieżdżone
  • Tagi początkowe i końcowe są takie same

Aby sprawdzić, czy ładunek XML lub JSON jest prawidłowo sformatowany:

  1. Dodaj zasadę weryfikacji wiadomości SOAP do przepływu wstępnego w punkcie końcowym serwera proxy.
  2. Usuń z definicji zasady elementy <ResourceURL>, <SOAPMessage> i <Element>.

    Definicja zasad 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 pokazano 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 jest ustawiony na „application/json”.

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

Powinna wyświetlić się odpowiedź HTTP 200. Gdy wysyłasz ładunek wiadomości, który nie zawiera poprawnie sformatowanego kodu XML lub JSON, powinien pojawić się błąd steps.messagevalidation.Failed.

Odniesienie do elementu podrzędnego

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

<DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną, bardziej naturalną nazwą.

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

Wartość domyślna nie dotyczy
Wymagany? Opcjonalnie. Jeśli pominiesz właściwość <DisplayName>, zostanie użyta wartość atrybutu name zasady
Typ Ciąg znaków
Element nadrzędny <PolicyElement>
Elementy podrzędne Brak

W elemencie <DisplayName> używana jest taka składnia:

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 pierwszy element podrzędny poniżej elementu <Body> w kopercie żądania SOAP.

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

W elemencie <Element> używana jest taka składnia:

Składnia

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

Przykład 1

W tym przykładzie zdefiniowano pojedynczy element do zweryfikowania:

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

Przykład 2

Możesz wskazać więcej niż 1 element do sprawdzenia, dodając kilka elementów <Element>:

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

Element <Element> ma te atrybuty:

Atrybut Domyślnie Wymagana? Opis
namespace "http://sample.com" Opcjonalnie Określa przestrzeń nazw elementu do zweryfikowania.

<ResourceURL>

Identyfikuje 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

W elemencie <ResourceURL> używana jest taka składnia:

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ć plik zasobów na serwerze proxy interfejsu API. Nie może odnosić się do zasobów zewnętrznych przez HTTP ani HTTPS.

Jeśli nie podasz wartości <ResourceURL>, wiadomość zostanie sprawdzona pod kątem poprawnego formatu JSON lub XML, jeśli nagłówek Content-type będzie mieć odpowiednio wartość „application/json” lub „application/xml”.

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

Używanie plików XSD do weryfikacji

Jeśli ładunek XML weryfikowany za pomocą zasady walidacji wiadomości odwołuje się do innego schematu, w atrybucie schemaLocation musisz dodać do dołączonego pliku XSD prefiks xsd.

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>

Weryfikacja przy użyciu WSDL

WSDL musi definiować co najmniej 1 schemat. Jeśli nie odwołuje się do co najmniej 1 schematu, zasada weryfikacji wiadomości nie zadziała.

Maksymalna głębokość importu schematu to 10. Jeśli przekroczysz liczbę zagnieżdżonych importów, zasada walidacji wiadomości nie zadziała.

<SOAPMessage>

Określa wersję SOAP, która jest weryfikowana przez zasadę walidacji wiadomości.

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

W elemencie <SOAPMessage> używana jest taka składnia:

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ślnie Wymagana? Opis
version Brak Opcjonalnie Wersja SOAP używana przez tę zasadę do weryfikowania wiadomości SOAP.

Prawidłowe wartości to:

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

Więcej informacji znajdziesz w artykule Przejście z SOAP/1.1 na SOAP w wersji 1.2 w 9 punktach.

<Source>

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

Jeśli nie ustawisz <Source>, ta zasada będzie domyślnie ustawiona na „message” (komunikat), który odnosi się do całej wiadomości żądania (w przepływie żądania) lub komunikatu odpowiedzi (w przepływie odpowiedzi), w tym całego ładunku. Możesz też ustawić bezpośrednie „żądanie” lub „odpowiedź”, aby odwołać się do żądania lub odpowiedzi.

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

W elemencie <Source> używana jest taka składnia:

Składnia

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

Przykład

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

Oprócz właściwości „message”, „żądanie” i „odpowiedź” możesz ustawić wartość <Source> na nazwę dowolnej wiadomości w przepływie. W takim przypadku musisz utworzyć w przepływie komunikat niestandardowy o tej nazwie, zanim ta zasada zostanie wykonana. W przeciwnym razie pojawi się błąd.

Jeśli wartości <Source> nie można rozpoznać w przepływie wiadomości lub przyjmuje się wartość inną niż wiadomość, występuje jedna z tych sytuacji:

  • Jeśli wartość null: Edge zgłasza błąd steps.messagevalidation.SourceMessageNotAvailable.
  • Jeśli typ nie jest wiadomości: Edge zgłasza błąd steps.messagevalidation.NonMessageVariable.

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 przewodniku po kodach 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