Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da Apigee Edge.
A política SOAPMessageValidation faz o seguinte:
- Valida qualquer mensagem XML em relação aos esquemas XSD
- Valida as mensagens SOAP em relação a uma definição WSDL
- Determina a boa formação das mensagens JSON e XML
Embora o nome dessa política na IU seja SOAPMessageValidation, a política valida mais do que apenas mensagens SOAP. Esta seção refere-se à política como política MessageValidation.
Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Nem todos os usuários têm necessidade de saber sobre os tipos de política e ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.
Elemento <MessageValidation>
Define a política MessageValidation.
Valor padrão | Consulte a guia Política padrão a seguir |
Obrigatório? | Opcional |
Tipo | Objeto complexo |
Elemento pai | n/a |
Elemento filho |
<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 padrão
O exemplo a seguir mostra as configurações padrão quando você adiciona uma política MessageValidation ao fluxo na IU da 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 | Padrão | Obrigatório? | Descrição |
---|---|---|---|
name |
N/A | Valor |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
continueOnError |
falso | Opcional | Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para
a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política
falhar. Consulte também:
|
enabled |
true | Opcional | Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo. |
async |
falso | Obsoleto | Esse atributo está obsoleto. |
Exemplos
Os exemplos a seguir mostram algumas maneiras de usar a política MessageValidation:
1: Validação de XSD
É possível usar a política de validação de mensagens para validar o payload de uma solicitação de mensagem XML em relação a um esquema XSD.
- Crie um novo arquivo de recurso XSD. 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 endpoint do proxy:
- Especifique o local do seu arquivo de recurso XSD com o elemento
<ResourceURL>
. 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 terá esta aparência:
<MessageValidation continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My XML Validator</DisplayName> <Properties/> <Source>request</Source> <ResourceURL>xsd://note-schema.xsd</ResourceURL> </MessageValidation>
- Especifique o local do seu arquivo de recurso XSD com o elemento
- Envie uma solicitação
POST
para o proxy de API com o XML como o payload da mensagem, como no exemplo a seguir: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>'
Observe que o cabeçalho
Content-type
está definido comoapplication/xml
.É possível também criar um arquivo de dados para o payload 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'
Você receberá uma resposta HTTP 200
. Dependendo do endpoint de destino, você poderá receber detalhes adicionais sobre a solicitação. Por exemplo, se você usar http://httpbin.org/post
como o endpoint de destino e especificar a saída -v
(detalhada), a resposta será semelhante a esta:
< 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 de XSD está funcionando, tente inserir outra tag no corpo da solicitação. 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>'
Você receberá um erro de validação.
2: Validação de SOAP
É possível usar a política de validação de mensagens para validar o payload de uma solicitação de mensagem SOAP em relação a um WSDL.
- Crie um novo arquivo de recursos WSDL. Por exemplo, "example-wsdl.wsdl":
- Adicione a política de validação de mensagens SOAP ao pré-fluxo do endpoint do proxy:
- Defina o atributo
version
do elemento<SOAPMessage>
como a versão do protocolo SOAP que você quer usar na validação. Por exemplo, "1.1":... <SOAPMessage version="1.1"/> ...
- Defina o valor do elemento
<Element>
como o elemento que você quer validar:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
especifica o primeiro filho abaixo do elemento<Body>
no envelope da solicitação SOAP.Defina o atributo
namespace
como o namespace desse filho. - Especifique o local do seu arquivo de recursos WSDL com o elemento
<ResourceURL>
. Exemplo:... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
A definição da política terá esta aparência:
<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 uma solicitação
POST
para o proxy de API com o envelope SOAP como o payload da mensagem, como mostra o exemplo a seguir: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>'
Observe que o cabeçalho
Content-type
está definido como "application/xml".É possível também criar um arquivo de dados para o payload 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'
Você receberá uma resposta HTTP 200
. Dependendo do endpoint de destino, você poderá receber detalhes adicionais sobre a solicitação. Por exemplo, se você usar
http://httpbin.org/post
como o endpoint de destino, a resposta será semelhante
a esta:
< 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 bem formado
Você pode usar a política de validação de mensagens para confirmar que um payload de mensagem JSON ou XML está bem formado (diferente da validação). A política garante que a estrutura e o conteúdo atendam aos padrões aceitos, incluindo:
- Há um único elemento raiz
- Não há caracteres inválidos no conteúdo
- Objetos e tags estão aninhados corretamente
- As tags de início e de término coincidem
Para verificar se um payload XML ou JSON está bem formado:
- Adicione a política de validação de mensagens SOAP ao pré-fluxo do endpoint do proxy.
- Remova os elementos
<ResourceURL>
,<SOAPMessage>
e<Element>
da definição da política.A definição da política terá esta aparência:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- Envie uma solicitação
POST
para seu proxy de API, como mostra o exemplo a seguir: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." } }'
Observe que o cabeçalho
Content-type
está definido comoapplication/json
.Para verificar se um arquivo XML foi bem formado, use XML como o payload da mensagem e defina
Content-type
comoapplication/xml
.
Você receberá uma resposta HTTP 200
. Quando você envia um payload de mensagem que não contém XML ou JSON bem formado, você recebe um erro steps.messagevalidation.Failed
.
Referência a elementos filhos
Esta seção descreve os elementos filhos de <MessageValidation>
.
<DisplayName>
Use além do atributo name
para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.
O elemento <DisplayName>
é comum a todas as políticas.
Valor padrão | N/A |
Obrigatório? | Opcional. Se você omitir <DisplayName> , o valor do atributo name da política será usado |
Tipo | String |
Elemento pai | <PolicyElement> |
Elemento filho | 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 ou elementos filhos.
<Element>
Especifica o elemento na mensagem a ser validada. Este é o primeiro filho abaixo do elemento <Body>
no envelope da solicitação SOAP.
Valor padrão | sampleObject |
Obrigatório? | Opcional |
Tipo | String |
Elemento pai |
<MessageValidation>
|
Elemento filho | Nenhum |
O elemento <Element>
usa a seguinte sintaxe:
Sintaxe
... <Element namespace="element_namespace">element_to_validate</Element> ...
Exemplo 1
O exemplo a seguir define um único elemento a ser validado:
... <Element namespace="https://example.com/gateway">getID</Element> ...
Exemplo 2
É possível especificar mais de um elemento a ser validado 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 | Padrão | Obrigatório? | Descrição |
---|---|---|---|
namespace |
"http://sample.com" | Opcional | Define o namespace do elemento a ser validado. |
<ResourceURL>
Identifica o esquema XSD ou a definição WSDL a ser usada para validar a mensagem de origem.
Valor padrão | wsdl://display_name.wsdl |
Obrigatório? | Opcional |
Tipo | String |
Elemento pai |
<MessageValidation>
|
Elemento filho | Nenhum |
O elemento <ResourceURL>
usa a seguinte sintaxe:
Sintaxe
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Exemplos
Para um arquivo XML:
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
Para um WSDL:
... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
O valor de <ResourceURL>
precisa apontar para um arquivo de recursos no seu proxy de API. Ele não pode se referir a recursos externos por HTTP ou HTTPS.
Se você não especificar um valor para<ResourceURL>
, a mensagem será verificada quanto a JSON ou XML
bem formado se o cabeçalho Content-type
for application/json
ou
application/xml
,
respectivamente.
O elemento <ResourceURL>
não tem elementos ou atributos filhos.
Como usar XSDs para validação
Se o payload XML que você validar com a política MessageValidation referenciar
outro esquema, será preciso prefixar o arquivo XSD incluído com xsd
no
atributo schemaLocation
.
O exemplo de esquema a seguir é composto de 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>
Como usar WSDLs para validação
Um WSDL precisa definir pelo menos um esquema. Se ele não referenciar pelo menos um esquema, a política MessageValidation falhará.
A profundidade de importação máxima de um esquema é dez. Se você exceder esse número de importações aninhadas, a política MessageValidation falhará.
<SOAPMessage>
Define a versão SOAP com que a política MessageValidation é validada.
Valor padrão | n/a |
Obrigatório? | Opcional |
Tipo | n/a |
Elemento pai |
<MessageValidation>
|
Elemento filho | 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 | Padrã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 De SOAP/1.1 para SOAP versão 1.2 em nove pontos.
<Source>
Identifica a mensagem de origem a ser validada. O valor desse elemento é o nome da mensagem a ser validada.
Se você não definir <Source>
, esta política terá como padrão message
, que se refere à mensagem completa da
solicitação (em um fluxo de solicitação) ou à mensagem de resposta (em um fluxo de resposta), incluindo qualquer
payload. Também é possível defini-la explicitamente como request
ou response
para se referir à solicitação ou
resposta.
Valor padrão | solicitação |
Obrigatório? | Opcional |
Tipo | String |
Elemento pai |
<MessageValidation>
|
Elemento filho | 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
, é possível definir o valor de
<Source>
como o nome de qualquer mensagem no fluxo. Se você fizer isso, será necessário criar uma mensagem personalizada com esse nome no fluxo antes da execução dessa política. Caso contrário, ocorrerá um erro.
Se o valor de <Source>
não puder ser resolvido no fluxo de mensagem ou for resolvido para um tipo sem mensagem, uma das seguintes situações ocorrerá:
- Se um valor nulo: a Apigee gera um erro
steps.messagevalidation.SourceMessageNotAvailable
. - Se um tipo sem mensagem: a Apigee gera um erro
steps.messagevalidation.NonMessageVariable
.
O elemento <Source>
não tem atributos ou elementos filhos.
Códigos de erro
Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Erros de execução
Esses erros podem ocorrer quando a política é executada.
Código de falha | Status HTTP | Causa | Correção |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
Esse erro ocorre se uma variável especificada no elemento
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Esse erro ocorrerá se o elemento As variáveis do tipo Message representam solicitações e respostas HTTP completas. As variáveis integradas do
fluxo da Apigee |
build |
steps.messagevalidation.Failed |
500 | Esse erro ocorrerá se a política SOAPMessageValidation não validar o payload da mensagem de entrada no esquema XSD ou na definição WSDL. Isso também ocorrerá se houver JSON ou XML malformado na mensagem de payload. | build |
Erros na implantação
Esses erros podem ocorrer quando você implanta um proxy que contém essa política.
Nome do erro | Causa | Corrigir |
---|---|---|
InvalidResourceType |
O elemento <ResourceURL> na política SOAPMessageValidation é definido como um tipo de recurso
não compatível com a política.
|
build |
ResourceCompileFailed |
O script de recurso referenciado no elemento <ResourceURL> da política
SOAPMessageValidation contém um erro que o impede de compilar.
|
build |
RootElementNameUnspecified |
O elemento <Element> na política SOAPMessageValidation não contém o nome do elemento raiz. |
build |
InvalidRootElementName |
O elemento <Element> na política SOAPMessageValidation contém um nome de elemento raiz
que não adere a regras XML para nomeação de elemento válida. |
build |
Esquemas
Cada tipo de política é definido por um esquema XML (.xsd
). Para referência, os esquemas de política
estão disponíveis no GitHub.
Temas relacionados
- Política de proteção contra ameaças XML
- Política XML para JSON
- Política JSON para XML
- Política de proteção contra ameaças JSON