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

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 <Source> da política for:

  • Fora do âmbito (não disponível no fluxo específico onde a política está a ser executada)
    • ou
  • não é possível resolver (não está definido)
steps.messagevalidation.NonMessageVariable 500

Este erro ocorre se o elemento <Source> na política SOAPMessageValidation estiver definido como uma variável que não seja do tipo message.

As variáveis de tipo de mensagem representam pedidos e respostas HTTP completos. As variáveis de fluxo incorporadas do Apigee request, response e message são do tipo de mensagem. Para saber mais acerca das variáveis de mensagens, consulte a referência de variáveis.
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.

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.
ResourceCompileFailed O script de recurso referenciado no elemento <ResourceURL> da política SOAPMessageValidation contém um erro que impede a sua compilação.
RootElementNameUnspecified O elemento <Element> na política SOAPMessageValidation não contém o nome do elemento raiz.
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.

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