Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
A política SOAPMessageValidation faz o seguinte:
- Valida qualquer mensagem XML de acordo com os respetivos esquemas XSD
- Valida mensagens SOAP com base numa definição WSDL
- Determina a correção formal das mensagens JSON e XML
Embora o nome desta política na IU seja SOAPMessageValidation, a política valida mais do que apenas mensagens SOAP. Esta secção refere-se à política como a Política de Validação de Mensagens.
Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.
<MessageValidation>
elemento
Define a política MessageValidation.
Valor predefinido | Consulte o separador Política predefinida abaixo |
Obrigatório? | Opcional |
Tipo | Objeto complexo |
Elemento principal | N/A |
Elementos subordinados |
<DisplayName> <Element> <ResourceURL> <SOAPMessage> <Source> |
Sintaxe
O elemento <MessageValidation>
usa a seguinte sintaxe:
<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>
Política predefinida
O exemplo seguinte mostra as predefinições quando adiciona uma política MessageValidation ao seu fluxo na IU do Apigee:
<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>
Este elemento tem os seguintes atributos comuns a todas as políticas:
Atributo | Predefinição | Obrigatório? | Descrição |
---|---|---|---|
name |
N/A | Obrigatório |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
continueOnError |
falso | Opcional | Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
|
enabled |
verdadeiro | Opcional | Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo. |
async |
falso | Descontinuado | Este atributo foi descontinuado. |
Exemplos
Os exemplos seguintes mostram algumas das formas como pode usar a política MessageValidation:
1: Validação XSD
Pode usar a política de validação de mensagens para validar a carga útil de um pedido de mensagem XML de acordo com um esquema XSD.
- Crie um novo ficheiro de recursos XSD. Por
exemplo,
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>
- Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy:
- Especifique a localização do ficheiro de recursos XSD com o elemento
<ResourceURL>
. Por exemplo:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- Remova os elementos
<SOAPMessage>
e<Element>
da definição da política.
A definição da política deve ter o seguinte aspeto:
<MessageValidation continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My XML Validator</DisplayName> <Properties/> <Source>request</Source> <ResourceURL>xsd://note-schema.xsd</ResourceURL> </MessageValidation>
- Especifique a localização do ficheiro de recursos XSD com o elemento
- Envie um pedido
POST
ao seu proxy de API com o XML como payload da mensagem, conforme mostra o exemplo seguinte: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>'
Repare que o cabeçalho
Content-type
está definido comoapplication/xml
.Também pode criar um ficheiro de dados para a carga útil e referenciá-lo com um comando semelhante ao seguinte:
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/note-payload.xml'
Deve receber uma resposta HTTP 200
. Consoante o ponto final de destino,
pode receber detalhes adicionais acerca do pedido. Por exemplo, se usar
http://httpbin.org/post
como o seu ponto final de destino e especificar -v
(detalhado), a resposta deve ser semelhante à seguinte:
< 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" }
Para verificar se a validação XSD está a funcionar, experimente inserir outra etiqueta no corpo do pedido. Por exemplo:
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>'
Deve receber um erro de validação.
2: validação SOAP
Pode usar a política de validação de mensagens para validar a carga útil de um pedido de mensagem SOAP em relação a um WSDL.
- Crie um novo ficheiro de recursos WSDL. Por exemplo, "example-wsdl.wsdl":
- Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy:
- Defina o atributo
version
do elemento<SOAPMessage>
para a versão do protocolo SOAP com a qual quer fazer a validação. Por exemplo, "1.1":... <SOAPMessage version="1.1"/> ...
- Defina o valor do elemento
<Element>
para o elemento que quer validar:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
especifica o primeiro elemento secundário no elemento<Body>
no envelope do pedido SOAP.Defina o atributo
namespace
para o espaço de nomes dessa criança. - Especifique a localização do ficheiro de recursos WSDL com o elemento
<ResourceURL>
. Por exemplo:... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
A definição da política deve ter o seguinte aspeto:
<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>
- Defina o atributo
- Envie um pedido
POST
ao proxy da API com o envelope SOAP como o payload da mensagem, como mostra o exemplo seguinte: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>'
Repare que o cabeçalho
Content-type
está definido como "application/xml".Também pode criar um ficheiro de dados para a carga útil e referenciá-lo com um comando semelhante ao seguinte:
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/soap-payload.xml'
Deve receber uma resposta HTTP 200
. Consoante o ponto final de destino,
pode receber detalhes adicionais acerca do pedido. Por exemplo, se usar
http://httpbin.org/post
como o seu ponto final de destino, a resposta deve ser semelhante
à seguinte:
< 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 formado corretamente
Pode usar a política de validação de mensagens para confirmar que uma carga útil de mensagens JSON ou XML tem um formato correto (não é o mesmo que a validação). A política garante que a estrutura e o conteúdo cumprem as normas aceites, incluindo:
- Existe um único elemento raíz
- Não existem carateres ilegais no conteúdo
- Os objetos e as etiquetas estão devidamente aninhados
- As etiquetas de início e de fim correspondem
Para verificar se um payload XML ou JSON tem um formato correto:
- Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy.
- Remova os elementos
<ResourceURL>
,<SOAPMessage>
> e<Element>
da definição da política.A definição da política deve ter o seguinte aspeto:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- Envie um pedido
POST
ao seu proxy de API, como mostra o exemplo seguinte: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." } }'
Repare que o cabeçalho
Content-type
está definido comoapplication/json
.Para verificar se um ficheiro XML está bem formado, use XML como o conteúdo útil da mensagem e defina
Content-type
comoapplication/xml
.
Deve receber uma resposta HTTP 200
. Quando envia um payload de mensagem que não contém XML ou JSON com formato correto, deve receber um erro steps.messagevalidation.Failed
.
Referência de elemento secundário
Esta secção descreve os elementos subordinados de <MessageValidation>
.
<DisplayName>
Use em conjunto com o atributo name
para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.
O elemento <DisplayName>
é comum a todas as políticas.
Valor predefinido | N/A |
Obrigatório? | Opcional. Se omitir <DisplayName> , é usado o valor do atributo name da política. |
Tipo | String |
Elemento principal | <PolicyElement> |
Elementos subordinados | Nenhum |
O elemento <DisplayName>
usa a seguinte sintaxe:
Sintaxe
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Exemplo
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
O elemento <DisplayName>
não tem atributos nem elementos subordinados.
<Element>
Especifica o elemento na mensagem a validar. Este é o primeiro elemento secundário do elemento <Body>
no envelope do pedido SOAP.
Valor predefinido | sampleObject |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<MessageValidation>
|
Elementos subordinados | Nenhum |
O elemento <Element>
usa a seguinte sintaxe:
Sintaxe
... <Element namespace="element_namespace">element_to_validate</Element> ...
Exemplo 1
O exemplo seguinte define um único elemento a ser validado:
... <Element namespace="https://example.com/gateway">getID</Element> ...
Exemplo 2
Pode especificar mais do que um elemento para validar adicionando vários elementos <Element>
:
... <Element namespace="https://example.com/gateway">getID</Element> <Element namespace="https://example.com/gateway">getDetails</Element> ...
O elemento <Element>
tem os seguintes atributos:
Atributo | Predefinição | Obrigatório? | Descrição |
---|---|---|---|
namespace |
"http://sample.com" | Opcional | Define o espaço de nomes do elemento a ser validado. |
<ResourceURL>
Identifica o esquema XSD ou a definição WSDL a usar para validar a mensagem de origem.
Valor predefinido | wsdl://display_name.wsdl |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<MessageValidation>
|
Elementos subordinados | Nenhum |
O elemento <ResourceURL>
usa a seguinte sintaxe:
Sintaxe
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Exemplos
Para um ficheiro XML:
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
Para um WSDL:
... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
O valor de <ResourceURL>
tem de apontar para um ficheiro de recursos no seu proxy da API. Não pode fazer referência a recursos externos através de HTTP ou HTTPS.
Se não especificar um valor para <ResourceURL>
, a mensagem é verificada quanto à existência de JSON
ou XML com formato correto se o cabeçalho Content-type
for application/json
ou
application/xml
, respetivamente.
O elemento <ResourceURL>
não tem elementos subordinados nem atributos.
Usar XSDs para validação
Se a carga útil XML que valida com a política MessageValidation fizer referência a outro esquema, tem de prefixar o ficheiro XSD incluído com xsd
no atributo schemaLocation
.
O esquema de exemplo seguinte é composto por vários XSDs:
<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>
Usar WSDLs para validação
Um WSDL tem de definir, pelo menos, um esquema. Se não fizer referência a, pelo menos, um esquema, a política MessageValidation falha.
A profundidade máxima de importação para um esquema é de 10. Se exceder esse número de importações aninhadas, a política de validação de mensagens falha.
<SOAPMessage>
Define a versão SOAP com base na qual a política MessageValidation é validada.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | N/A |
Elemento principal |
<MessageValidation>
|
Elementos subordinados | Nenhum |
O elemento <SOAPMessage>
usa a seguinte sintaxe:
Sintaxe
... <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/> ...
Exemplo
... <SOAPMessage version="1.1"/> ...
O elemento <SOAPMessage>
tem os seguintes atributos:
Atributo | Predefinição | Obrigatório? | Descrição |
---|---|---|---|
version |
Nenhum | Opcional | A versão SOAP que esta política usa para validar mensagens SOAP.
Os valores válidos são:
|
Para mais informações, consulte o artigo Do SOAP/1.1 ao SOAP versão 1.2 em 9 pontos.
<Source>
Identifica a mensagem de origem a validar. O valor deste elemento é o nome da mensagem que quer validar.
Se não definir <Source>
, esta política é predefinida como message
, que se refere à mensagem de pedido completa (num fluxo de pedido) ou à mensagem de resposta (num fluxo de resposta), incluindo qualquer payload. Também pode defini-lo explicitamente como request
ou response
para se referir ao pedido ou à resposta.
Valor predefinido | pedido |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<MessageValidation>
|
Elementos subordinados | Nenhum |
O elemento <Source>
usa a seguinte sintaxe:
Sintaxe
... <Source>message_to_validate</Source> ...
Exemplo
... <Source>request</Source> ...
Além de message
, request
e response
, pode definir o valor de
<Source>
para o nome de qualquer mensagem no seu fluxo. No entanto, se o fizer, tem de criar uma mensagem personalizada com esse nome no fluxo antes de esta política ser executada. Caso contrário, recebe um erro.
Se o valor de <Source>
não puder ser resolvido no fluxo de mensagens ou for resolvido para um tipo que não seja de mensagem, ocorre uma das seguintes situações:
- Se um valor nulo: o Apigee lança um erro
steps.messagevalidation.SourceMessageNotAvailable
. - Se for um tipo que não seja de mensagem: o Apigee gera um erro
steps.messagevalidation.NonMessageVariable
.
O elemento <Source>
não tem atributos nem elementos subordinados.
Códigos de erro
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
This error occurs if a variable specified in the
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
This error occurs if the Message type variables represent entire HTTP requests and responses. The built-in Apigee
flow variables |
build |
steps.messagevalidation.Failed |
500 | This error occurs if the SOAPMessageValidation policy fails to validate the input message payload against the XSD schema or WSDL definition. It will also occur if there is malformed JSON or XML in the payload message. | build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
InvalidResourceType |
The <ResourceURL> element in the SOAPMessageValidation policy is set to a resource type
not supported by the policy.
|
build |
ResourceCompileFailed |
The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation
policy contains an error that prevents it from compiling.
|
build |
RootElementNameUnspecified |
The <Element> element in the SOAPMessageValidation policy does not contain the root
element's name. |
build |
InvalidRootElementName |
The <Element> element in the SOAPMessageValidation policy contains a root element name
that does not adhere to XML rules for valid element naming. |
build |
Esquemas
Cada tipo de política é definido por um esquema XML (.xsd
). Para referência, os esquemas de políticas
estão disponíveis no GitHub.
Tópicos relacionados
- Política de proteção contra ameaças XML
- Política de XML para JSON
- Política de JSON para XML
- Política de proteção contra ameaças JSON