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 Opcjonalnie użyj elementu |
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.
- 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>
- Dodaj zasadę weryfikacji wiadomości SOAP do procesu wstępnego w punkcie końcowym serwera proxy:
- Określ lokalizację pliku zasobów XSD za pomocą elementu
<ResourceURL>
. Przykład:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- 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>
- Określ lokalizację pliku zasobów XSD za pomocą elementu
- 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.
- Utwórz nowy plik zasobów WSDL. Na przykład „example-wsdl.wsdl”:
- Dodaj zasadę weryfikacji wiadomości SOAP do procesu wstępnego w punkcie końcowym serwera proxy:
- 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"/> ...
- 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. - 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>
- Ustaw atrybut
- 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:
- Dodaj zasadę weryfikacji wiadomości SOAP do przepływu wstępnego w punkcie końcowym serwera proxy.
- 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>
- 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:
|
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
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Ten błąd występuje, jeśli element Zmienne typu wiadomości reprezentują całe żądania i odpowiedzi HTTP. Wbudowane zmienne przepływu Edge |
build |
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. | build |
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ę.
|
build |
ResourceCompileFailed |
Skrypt zasobów, do którego odwołuje się element <ResourceURL> zasady SOAPMessageValidation, zawiera błąd uniemożliwiający mu kompilowanie.
|
build |
RootElementNameUnspecified |
Element <Element> w zasadzie SOAPMessageValidation nie zawiera nazwy elementu głównego. |
build |
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. |
build |
Schematy
Każdy typ zasad jest definiowany przez schemat XML (.xsd
). Schematy zasad są dostępne na GitHubie.