Política SOAPMessageValidation

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

La política SOAPMessageValidation hace lo siguiente:

  • Valida cualquier mensaje XML en relación con sus esquemas XSD
  • Valida los mensajes SOAP en relación con una definición de WSDL
  • Determina el formato adecuada de los mensajes JSON y XML

Si bien el nombre de esta política en la IU es SOAPMessageValidation, la política valida más que solo los mensajes SOAP. En esta sección, se hace referencia a la política como la política de MessageValidation.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Elemento <MessageValidation>

Define la política MessageValidation.

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio? Opcional
Tipo Objeto complejo
Elemento principal n/a
Elementos secundarios <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

Sintaxis

El elemento <MessageValidation> usa la siguiente sintaxis:

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

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de MessageValidation a tu flujo en la IU de 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 tiene los siguientes atributos que son comunes a todas las políticas:

Atributo Predeterminada (obligatorio) Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

continueOnError falso Opcional Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta Este atributo dejó de estar disponible.

Ejemplos

En los siguientes ejemplos, se muestran algunas de las formas en las que puedes usar la política MessageValidation:

1: Validación de XSD

Puedes usar la política de validación de mensajes para validar la carga útil de una solicitud de mensaje XML en relación con un esquema XSD.

  1. Crea un nuevo archivo de recursos XSD. Por ejemplo, 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. Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo de tu extremo de proxy:
    1. Especifica la ubicación de tu archivo de recursos XSD con el elemento <ResourceURL>. Por ejemplo:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Quita los elementos <SOAPMessage> y <Element> de la definición de la política.

    Tu definición de política debería verse así:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. Envía una solicitud POST al proxy de tu API con tu XML como carga útil del mensaje de la siguiente manera:
    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>'

    Observa que el encabezado Content-type se configuró como application/xml.

    También puedes crear un archivo de datos para la carga útil y hacer referencia a él con un comando similar al siguiente:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

Deberías recibir una respuesta HTTP 200. Según el extremo objetivo, es posible que recibas detalles adicionales sobre la solicitud. Por ejemplo, si usas http://httpbin.org/post como tu extremo de destino y especificas un resultado -v (detallado), la respuesta debería ser similar a la siguiente:

< 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 que tu validación de XSD funcione, intenta insertar otra etiqueta en el cuerpo de tu solicitud. Por ejemplo:

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

Deberías recibir un error de validación.

2: Validación de SOAP

Puedes usar la política de validación de mensajes para validar la carga útil de una solicitud de mensaje SOAP en una WSDL.

  1. Crea un archivo de recursos WSDL nuevo. Por ejemplo, “example-wsdl.wsdl”:
  2. Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo del extremo del proxy:
    1. Configura el atributo version del elemento <SOAPMessage> en la versión del protocolo SOAP con el que deseas validar. Por ejemplo, “1.1”:
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. Configura el valor del elemento <Element> en el elemento que deseas validar:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element> especifica el primer elemento secundario debajo del elemento <Body> en el sobre de la solicitud SOAP.

      Configura el atributo namespace en el espacio de nombres para ese elemento secundario.

    3. Especifica la ubicación de tu archivo de recursos WSDL con el elemento <ResourceURL>. Por ejemplo:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    Tu definición de política debería verse así:

    <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. Envía una solicitud POST al proxy de la API con el sobre SOAP como la carga útil del mensaje, como se muestra en el siguiente ejemplo:
    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>'

    Observa que el encabezado Content-type está configurado como "application/xml".

    También puedes crear un archivo de datos para la carga útil y hacer referencia a él con un comando similar al siguiente:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

Deberías recibir una respuesta HTTP 200. Según el extremo objetivo, es posible que recibas detalles adicionales sobre la solicitud. Por ejemplo, si usas http://httpbin.org/post como tu extremo de destino, la respuesta debería ser similar a la siguiente:

< 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 con formato adecuado

Puedes usar la política de validación de mensajes para confirmar que una carga útil de mensaje JSON o XML tenga el formato correcto (no es igual que la validación). La política garantiza que la estructura y el contenido cumplan con los estándares aceptados, que incluyen lo siguiente:

  • Que haya un solo elemento raíz
  • Que no haya caracteres ilegales en el contenido
  • Que los objetos y las etiquetas estén anidados correctamente
  • Que las etiquetas de inicio y fin coincidan

Para comprobar si hay una carga útil con formato XML o JSON, haz lo siguiente:

  1. Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo del extremo del proxy:
  2. Quita los elementos <ResourceURL>, <SOAPMessage> y <Element> de la definición de la política.

    Tu definición de política debería verse así:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. Envía una solicitud POST a tu proxy de API de la siguiente manera:
    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."
      }
    }'

    Observa que el encabezado Content-type se configuró como application/json.

    Para comprobar si hay un formato correcto en un archivo XML, usa XML como carga útil del mensaje y configura Content-type como application/xml.

Deberías recibir una respuesta HTTP 200. Si envías una carga útil del mensaje que no contiene XML o JSON con el formato correcto, deberías recibir un error steps.messagevalidation.Failed.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <MessageValidation>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado N/A
¿Es obligatorio? Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo String
Elemento principal <PolicyElement>
Elementos secundarios Ninguna

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Element>

Especifica el elemento que se debe validar en el mensaje. Este es el primer elemento secundario dentro del elemento <Body> en el sobre de la solicitud SOAP.

Valor predeterminado sampleObject
(obligatorio) Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguna

El elemento <Element> usa la siguiente sintaxis:

Sintaxis

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

Ejemplo 1

El siguiente ejemplo define un solo elemento que se validará:

...
<Element namespace="https://example.com/gateway">getID</Element>
...

Ejemplo 2

Puedes especificar más de un elemento para validar si agregas varios elementos <Element>:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

El elemento <Element> tiene los siguientes atributos:

Atributo Predeterminada ¿Es obligatorio? Descripción
namespace "http://sample.com" Opcional Define el espacio de nombres del elemento que se validará.

<ResourceURL>

Identifica el esquema XSD o la definición WSDL que se utilizará para validar el mensaje fuente.

Valor predeterminado wsdl://display_name.wsdl
(obligatorio) Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguna

El elemento <ResourceURL> usa la siguiente sintaxis:

Sintaxis

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

Ejemplos

Para un archivo XML:

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

Para un WSDL:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

El valor de <ResourceURL> debe apuntar a un archivo de recursos en tu proxy de API. Este no puede hacer referencia a recursos externos a través de HTTP o HTTPS.

Si no especificas un valor para<ResourceURL>, se verifica si el mensaje tiene un formato JSON o XML bien formado, si elContent-type el encabezado esapplication/json oapplication/xml, respectivamente.

El elemento <ResourceURL> no tiene elementos secundarios ni atributos.

Usa XSD para la validación

Si la carga útil XML que validas con la política de MessageValidation hace referencia a otro esquema, debes poner el prefijo xsd el archivo XSD incluido en el atributo schemaLocation.

El siguiente esquema de ejemplo está compuesto por varios XSD:

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

Cómo usar WSDL para la validación

Un WSDL debe definir al menos un esquema. Si no hace referencia a, por lo menos, un esquema, la política MessageValidation falla.

La profundidad máxima de importación de un esquema es 10. Si excedes esa cantidad de importaciones anidadas, la política de MessageValidation falla.

<SOAPMessage>

Define la versión de SOAP con respecto a la que valida la política de MessageValidation.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo N/A
Elemento principal <MessageValidation>
Elementos secundarios Ninguna

El elemento <SOAPMessage> usa la siguiente sintaxis:

Sintaxis

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

Ejemplo

...
<SOAPMessage version="1.1"/>
...

El elemento <SOAPMessage> tiene los siguientes atributos:

Atributo Predeterminada ¿Es obligatorio? Descripción
version None Opcional La versión de SOAP que usa esta política para validar mensajes SOAP.

Estos son los valores válidos:

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

Para obtener más información, consulta Desde SOAP/1.1 hasta SOAP versión 1.2 en 9 puntos.

<Source>

Identifica el mensaje fuente que se validará. El valor de este elemento es el nombre del mensaje que deseas validar.

Si no estableces <Source>, esta política se establece de forma predeterminada en message, que hace referencia al mensaje de solicitud completo (en un flujo de solicitud) o al mensaje de respuesta (en un flujo de respuesta), incluida cualquier carga útil. También puedes configurarlo de forma explícita en request o response para hacer referencia a la solicitud o respuesta.

Valor predeterminado solicitud
(obligatorio) Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguna

El elemento <Source> usa la siguiente sintaxis:

Sintaxis

...
  <Source>message_to_validate</Source>
...

Ejemplo

...
<Source>request</Source>
...

Además de message, request y response, puedes establecer el valor de <Source> en el nombre de cualquier mensaje de tu flujo. Sin embargo, si lo haces, debes crear un mensaje personalizado con ese nombre en tu flujo antes de que se ejecute esta política. De lo contrario, aparecerá un error.

Si el valor de <Source> no se puede resolver en el flujo de mensajes, o se resuelve en un tipo que no es de mensaje, se produce una de las siguientes situaciones:

  • Si hay un valor nulo: Apigee muestra un error steps.messagevalidation.SourceMessageNotAvailable.
  • Si es un tipo que no es de mensaje: Apigee genera un error steps.messagevalidation.NonMessageVariable.

El elemento <Source> no tiene atributos ni elementos secundarios.

Códigos de error

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

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Temas relacionados