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. 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 No disponible
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 Ninguno

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
¿Es obligatorio? Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguno

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 Predeterminado ¿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
¿Es obligatorio? Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguno

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 Ninguno

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 Predeterminado ¿Es obligatorio? Descripción
version Ninguna 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
¿Es obligatorio? Opcional
Tipo String
Elemento principal <MessageValidation>
Elementos secundarios Ninguno

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

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa Corregir
steps.messagevalidation.SourceMessageNotAvailable 500

Este error se produce si una variable especificada en el elemento <Source> de la política:

  • Está fuera del alcance (no está disponible en el flujo específico en el que se ejecuta la política)
  • o
  • no se puede resolver (no está definido)
steps.messagevalidation.NonMessageVariable 500

Este error ocurre si el elemento <Source> en la política SOAPMessageValidation está configurado en una variable que no es del tipo mensaje.

Las variables del tipo de mensaje representan respuestas y solicitudes HTTP completas. Las variables de flujo integradas de Apigee request, response y message son de tipo de mensaje. Para obtener más información acerca de las variables de mensaje, consulta la Referencia de las variables.

steps.messagevalidation.Failed 500 Este error se produce si la política SOAPMessageValidation no valida la carga útil del mensaje de entrada en función del esquema XSD o la definición WSDL. También ocurrirá si hay JSON o XML de formato incorrecto en el mensaje de carga útil.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa Corregir
InvalidResourceType El elemento <ResourceURL> en la política SOAPMessageValidation se establece en un tipo de recurso que no es compatible con la política.
ResourceCompileFailed La secuencia de comandos de recursos a la que se hace referencia en el elemento <ResourceURL> de la política SOAPMessageValidation contiene un error que impide que se compile.
RootElementNameUnspecified El elemento <Element> en la política SOAPMessageValidation no contiene el nombre del elemento raíz.
InvalidRootElementName El elemento <Element> en la política SOAPMessageValidation contiene un nombre de elemento raíz que no cumple con las reglas XML para nombrar nombres de elementos válidos.

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