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
Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.
Erros de tempo de execução
Estes erros podem ocorrer quando a política é executada.
Código de falha | Estado de HTTP | Causa | Corrigir |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
Este erro ocorre se uma variável especificada no elemento
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Este erro ocorre se o elemento As variáveis de tipo de mensagem representam pedidos e respostas HTTP completos. As variáveis de fluxo incorporadas do Apigee |
build |
steps.messagevalidation.Failed |
500 | Este erro ocorre se a política SOAPMessageValidation não conseguir validar a carga útil da mensagem de entrada em relação ao esquema XSD ou à definição WSDL. Também ocorre se houver JSON ou XML com formato incorreto na mensagem de payload. | build |
Erros de implementação
Estes erros podem ocorrer quando implementa um proxy que contém esta política.
Nome do erro | Causa | Corrigir |
---|---|---|
InvalidResourceType |
O elemento <ResourceURL> na política SOAPMessageValidation está definido para um tipo de recurso
não suportado pela política.
|
build |
ResourceCompileFailed |
O script de recurso referenciado no elemento <ResourceURL> da política SOAPMessageValidation
contém um erro que impede a sua compilação.
|
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 cumpre as regras XML para a nomenclatura de elementos válidos. |
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