Política SOAPMessageValidation

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone de política

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 name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
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.

  1. 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>
  2. Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy:
    1. Especifique a localização do ficheiro de recursos XSD com o elemento <ResourceURL>. Por 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 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>
  3. 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 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/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.

  1. Crie um novo ficheiro de recursos WSDL. Por exemplo, "example-wsdl.wsdl":
  2. Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy:
    1. 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"/>
...
    2. 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.

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

  1. Adicione a política de validação de mensagens SOAP ao pré-fluxo do ponto final do proxy.
  2. 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>
  3. 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 como application/json.

    Para verificar se um ficheiro XML está bem formado, use XML como o conteúdo útil da mensagem e defina Content-type como application/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:

  • "1.1"
  • "1.2"
  • "1.1/1.2"

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

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íticas estão disponíveis no GitHub.

Tópicos relacionados