Política SOAPMessageValidation

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. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Sobre a política MessageValidation

Benefícios

A validação de mensagens oferece os seguintes benefícios:

• Informa imediatamente os desenvolvedores de apps que estão consumindo a API caso as solicitações não estejam em conformidade ou completas.
• Identifica problemas nas solicitações, como tags XML que não estão fechadas adequadamente.
• Protege serviços de back-end bloqueando mensagens XML ou SOAP com estruturas que possam causar um comportamento imprevisível.
• Reduz o tempo gasto na solução de problemas, na pesquisa em fóruns ou na consultoria com suporte técnico.
• Incentiva os desenvolvedores a se familiarizar com a definição WSDL do esquema XML para eliminar erros de validação, o que torna os esquemas XML bem compreendidos um componente essencial da documentação da API.

Vídeos

Assista aos vídeos abaixo para saber mais sobre a política MessageValidation:

Vídeo	Descrição
Validar a solicitação XML	Valide a solicitação XML para uma API usando a política MessageValidation.
Validar a solicitação JSON	Valide a solicitação JSON para uma API usando a política MessageValidation.

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>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

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.

1. 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>

2. Adicione a política de validação de mensagens SOAP ao pré-fluxo do endpoint do proxy:
   1. Especifique o local do seu arquivo de recurso XSD com o elemento <ResourceURL>. Exemplo:

      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...

   2. 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>

3. 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 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/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.

1. Crie um novo arquivo de recursos WSDL. Por exemplo, "example-wsdl.wsdl":

   Ver o WSDL completo

   <?xml version="1.0" encoding="UTF-8"?>
   <wsdl:definitions targetNamespace="https://example.com/gateway"
       xmlns:tns="https://example.com/gateway"
       xmlns:types="https://example.com/gateway/types"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
       xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">
     <wsdl:types>
       <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           targetNamespace="https://example.com/gateway/types"
           elementFormDefault="qualified">
         <xsd:element name="MyType">
           <xsd:complexType>
             <xsd:sequence>
               <xsd:element name="ID" nillable="false" minOccurs="1" maxOccurs="1"/>
             </xsd:sequence>
           </xsd:complexType>
         </xsd:element>
       </xsd:schema>
       <schema attributeFormDefault="unqualified" elementFormDefault="qualified"
           targetNamespace="https://example.com/gateway"
           xmlns="http://www.w3.org/2001/XMLSchema">
         <xsd:import namespace="https://example.com/gateway/types"/>
         <element name="getID">
           <complexType>
             <sequence>
               <element ref="types:MyType"/>
             </sequence>
           </complexType>
         </element>
       </schema>
     </wsdl:types>
   
     <wsdl:message name="getRequest">
       <wsdl:part name="getRequest" element="tns:getID"/>
     </wsdl:message>
     <wsdl:message name="getResponse">
       <wsdl:part name="getResponse" element="tns:getID"/>
     </wsdl:message>
   
     <wsdl:portType name="PortType">
       <wsdl:operation name="get">
         <wsdl:input name="methodRequest" message="tns:getRequest"/>
         <wsdl:output name="methodResponse" message="tns:getResponse"/>
       </wsdl:operation>
     </wsdl:portType>
   
     <wsdl:service name="Gateway">
       <wsdl:port name="GatewaySoap" binding="tns:SoapBinding">
         <wsdlsoap:address location="https://example.com/gateway"/>
       </wsdl:port>
     </wsdl:service>
   
     <wsdl:binding name="SoapBinding" type="tns:PortType">
       <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
   
       <wsdl:operation name="get">
         <wsdlsoap:operation soapAction="get"/>
         <wsdl:input name="methodRequest"/>
         <wsdl:output name="methodResponse"/>
       </wsdl:operation>
   
     </wsdl:binding>
   </wsdl:definitions>

2. Adicione a política de validação de mensagens SOAP ao pré-fluxo do endpoint do proxy:
   1. 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"/>
      ...

   2. 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.

   3. 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>

3. 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:

1. Adicione a política de validação de mensagens SOAP ao pré-fluxo do endpoint do proxy.
2. 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>

3. 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 como application/json.

   Para verificar se um arquivo XML foi bem formado, use XML como o payload da mensagem e defina Content-type como application/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>

Observação: você só poderá incluir ou importar XSDs se forem arquivos de recursos no seu proxy de API. Não é possível incluir arquivos XSD externos.

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: "1.1" "1.2" "1.1/1.2"

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

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.

Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Use API Monitoring to investigate fault codes and diagnose issues faster. See Set up a policy fault code alert for an example. See Fault code reference for a complete list of all fault codes that you can handle with API Monitoring.

Fault code	HTTP status	Cause	Fix
steps.messagevalidation.SourceMessageNotAvailable	500	This error occurs if a variable specified in the <Source> element of the policy is either: out of scope (not available in the specific flow where the policy is being executed) or can't be resolved (is not defined)
steps.messagevalidation.NonMessageVariable	500	This error occurs if the <Source> element in the SOAPMessageValidation policy is set to a variable which is not of type message. Message type variables represent entire HTTP requests and responses. The built-in Apigee flow variables request, response, and message are of type message. To learn more about message variables, see the Variables reference.
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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

Error name	Cause	Fix
InvalidResourceType	The <ResourceURL> element in the SOAPMessageValidation policy is set to a resource type not supported by the policy.
ResourceCompileFailed	The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation policy contains an error that prevents it from compiling.
RootElementNameUnspecified	The <Element> element in the SOAPMessageValidation policy does not contain the root element's name.
InvalidRootElementName	The <Element> element in the SOAPMessageValidation policy contains a root element name that does not adhere to XML rules for valid element naming.

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