Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
La política SOAPMessageValidation hace lo siguiente:
- Valida cualquier mensaje XML con sus esquemas XSD
- Valida mensajes SOAP con una definición WSDL.
- Determina si los mensajes JSON y XML tienen el formato correcto.
Aunque el nombre de esta política en la interfaz de usuario es SOAPMessageValidation, la política valida más que solo mensajes SOAP. En esta sección se hace referencia a la política como MessageValidation policy.
Esta política 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 de 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 que aparece más abajo. |
¿Es obligatorio? | Opcional |
Tipo | Objeto complejo |
Elemento principal | n/a |
Elementos secundarios |
<DisplayName> <Element> <ResourceURL> <SOAPMessage> <Source> |
Sintaxis
El elemento <MessageValidation>
utiliza 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 muestran los ajustes predeterminados al añadir una política MessageValidation a tu flujo en la interfaz de usuario 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 | Predeterminado | ¿Es obligatorio? | Descripción |
---|---|---|---|
name |
N/A | Obligatorio |
El nombre interno de la política. El valor del atributo Opcionalmente, usa el elemento |
continueOnError |
falso | Opcional | Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:
|
enabled |
true | Opcional | Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo. |
async |
falso | Obsoleto | Este atributo está obsoleto. |
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 con un esquema XSD.
- Crea un 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>
- Añade la política de validación de mensajes SOAP al pre-flow del endpoint de proxy:
- Especifica la ubicación del archivo de recursos XSD con el elemento
<ResourceURL>
. Por ejemplo:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- Elimina los elementos
<SOAPMessage>
y<Element>
de la definición de la política.
La definición de la política debería tener el siguiente aspecto:
<MessageValidation continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My XML Validator</DisplayName> <Properties/> <Source>request</Source> <ResourceURL>xsd://note-schema.xsd</ResourceURL> </MessageValidation>
- Especifica la ubicación del archivo de recursos XSD con el elemento
- Envía una solicitud
POST
a tu proxy de API con tu XML como 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 '<note> <to>Fred Rogers</to> <from>Nick Danger</from> <heading>Greetings from my neighborhood</heading> <body>Just writing to say hello.</body> </note>'
Verás que el encabezado
Content-type
tiene el valorapplication/xml
.También puede 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
. En función del endpoint de destino, es posible que recibas más detalles sobre la solicitud. Por ejemplo, si usa http://httpbin.org/post
como endpoint de destino y especifica la salida -v
(detallada), 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 la validación XSD funciona, prueba a 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 SOAP
Puede usar la política de validación de mensajes para validar la carga útil de una solicitud de mensaje SOAP con un WSDL.
- Crea un archivo de recursos WSDL. Por ejemplo, "example-wsdl.wsdl":
- Añade la política de validación de mensajes SOAP al pre-flow del endpoint de proxy:
- Asigna al atributo
version
del elemento<SOAPMessage>
la versión del protocolo SOAP con la que quieras validar el contenido. Por ejemplo, "1.1":... <SOAPMessage version="1.1"/> ...
- Asigna al elemento
<Element>
el elemento que quieras validar:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
especifica el primer elemento secundario del elemento<Body>
en el sobre de la solicitud SOAP.Asigna el atributo
namespace
al espacio de nombres de ese elemento secundario. - Especifica la ubicación del archivo de recursos WSDL con el elemento
<ResourceURL>
. Por ejemplo:... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
La definición de la política debería tener el siguiente aspecto:
<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>
- Asigna al atributo
- Envía una solicitud
POST
a tu proxy de API con el sobre SOAP como 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>'
Ten en cuenta que el encabezado
Content-type
es "application/xml".También puede 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
. En función del endpoint de destino, es posible que recibas más detalles sobre la solicitud. Por ejemplo, si usa
http://httpbin.org/post
como endpoint 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 o JSON bien formado
Puedes usar la política de validación de mensajes para confirmar que la carga útil de un mensaje JSON o XML tiene el formato correcto (no es lo mismo que la validación). La política asegura que la estructura y el contenido cumplan los estándares aceptados, entre los que se incluyen los siguientes:
- Hay un solo elemento raíz
- El contenido no contiene caracteres no permitidos
- Los objetos y las etiquetas están anidados correctamente
- Las etiquetas de inicio y de cierre coinciden
Para comprobar si una carga útil XML o JSON tiene un formato correcto, sigue estos pasos:
- Añade la política de validación de mensajes SOAP al pre-flow del endpoint de proxy.
- Elimina los elementos
<ResourceURL>
,<SOAPMessage>
y<Element>
de la definición de la política.La definición de la política debería tener el siguiente aspecto:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- Envía una solicitud
POST
a tu proxy de API, como se muestra en el siguiente ejemplo: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." } }'
Verás que el encabezado
Content-type
tiene el valorapplication/json
.Para comprobar si un archivo XML está bien formado, use XML como carga útil del mensaje y defina
Content-type
comoapplication/xml
.
Deberías recibir una respuesta HTTP 200
. Cuando envías una carga útil de mensaje
que no contiene XML o JSON con el formato correcto, deberías recibir un error steps.messagevalidation.Failed
.
Referencia de elemento secundario
En esta sección se describen los elementos secundarios de <MessageValidation>
.
<DisplayName>
Se usa junto con el atributo name
para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.
El elemento <DisplayName>
es común a todas las políticas.
Valor predeterminado | N/A |
¿Es obligatorio? | Opcional. Si omite <DisplayName> , se usará el valor del atributo name de la política. |
Tipo | Cadena |
Elemento principal | <PolicyElement> |
Elementos secundarios | Ninguno |
El elemento <DisplayName>
utiliza 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 del mensaje que se va a validar. Es el primer elemento secundario del elemento <Body>
del sobre de la solicitud SOAP.
Valor predeterminado | sampleObject |
¿Es obligatorio? | Opcional |
Tipo | Cadena |
Elemento principal |
<MessageValidation>
|
Elementos secundarios | Ninguno |
El elemento <Element>
utiliza la siguiente sintaxis:
Sintaxis
... <Element namespace="element_namespace">element_to_validate</Element> ...
Ejemplo 1
En el siguiente ejemplo se define un solo elemento que se va a validar:
... <Element namespace="https://example.com/gateway">getID</Element> ...
Ejemplo 2
Puedes especificar más de un elemento para validar añadiendo 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 va a validar. |
<ResourceURL>
Identifica el esquema XSD o la definición WSDL que se va a usar para validar el mensaje de origen.
Valor predeterminado | wsdl://display_name.wsdl |
¿Es obligatorio? | Opcional |
Tipo | Cadena |
Elemento principal |
<MessageValidation>
|
Elementos secundarios | Ninguno |
El elemento <ResourceURL>
utiliza la siguiente sintaxis:
Sintaxis
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Ejemplos
En el caso de un archivo XML:
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
En el caso de un WSDL:
... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
El valor de <ResourceURL>
debe apuntar a un archivo de recursos de su proxy de API. No puede hacer referencia a recursos externos a través de HTTP o HTTPS.
Si no especifica un valor para <ResourceURL>
, se comprobará si el mensaje tiene un formato JSON o XML correcto, en función de si el encabezado Content-type
es application/json
o application/xml
, respectivamente.
El elemento <ResourceURL>
no tiene elementos secundarios ni atributos.
Usar XSDs para la validación
Si la carga útil XML que valida con la política MessageValidation hace referencia a otro esquema, debe añadir el prefijo xsd
al archivo XSD incluido en el atributo schemaLocation
.
El siguiente esquema de ejemplo se compone de varios 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 la validación
Un WSDL debe definir al menos un esquema. Si no hace referencia a al menos un esquema, la política MessageValidation falla.
La profundidad máxima de importación de un esquema es 10. Si superas ese número de importaciones anidadas, la política MessageValidation fallará.
<SOAPMessage>
Define la versión de SOAP con la que se valida la política MessageValidation.
Valor predeterminado | n/a |
¿Es obligatorio? | Opcional |
Tipo | n/a |
Elemento principal |
<MessageValidation>
|
Elementos secundarios | Ninguno |
El elemento <SOAPMessage>
utiliza 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 |
Ninguno | Opcional | La versión de SOAP que usa esta política para validar los mensajes SOAP.
Los valores válidos son estos:
|
Para obtener más información, consulta el artículo De SOAP/1.1 a SOAP versión 1.2 en 9 puntos.
<Source>
Identifica el mensaje de origen que se va a validar. El valor de este elemento es el nombre del mensaje que quieres validar.
Si no defines <Source>
, esta política tendrá el valor predeterminado message
, que hace referencia al mensaje de solicitud completo (en un flujo de solicitudes) o al mensaje de respuesta (en un flujo de respuestas), incluida cualquier carga útil. También puedes asignarle explícitamente el valor request
o response
para hacer referencia a la solicitud o a la respuesta.
Valor predeterminado | solicitud |
¿Es obligatorio? | Opcional |
Tipo | Cadena |
Elemento principal |
<MessageValidation>
|
Elementos secundarios | Ninguno |
El elemento <Source>
utiliza la siguiente sintaxis:
Sintaxis
... <Source>message_to_validate</Source> ...
Ejemplo
... <Source>request</Source> ...
Además de message
, request
y response
, puedes asignar a <Source>
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, se producirá 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, ocurre una de las siguientes situaciones:
- Si el valor es nulo: Apigee genera un error
steps.messagevalidation.SourceMessageNotAvailable
. - Si no es un tipo 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 error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.
Errores de tiempo de ejecución
Estos errores pueden producirse cuando se ejecuta la política.
Código de fallo | Estado de HTTP | Causa | Solucionar |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
Este error se produce si una variable especificada en el elemento
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Este error se produce si el elemento Las variables de tipo de mensaje representan solicitudes y respuestas HTTP completas. Las variables de flujo integradas de Apigee |
build |
steps.messagevalidation.Failed |
500 | Este error se produce si la política SOAPMessageValidation no puede validar la carga útil del mensaje de entrada con el esquema XSD o la definición WSDL. También se producirá si el mensaje de carga útil contiene JSON o XML con formato incorrecto. | build |
Errores de implementación
Estos errores pueden producirse al implementar un proxy que contenga esta política.
Nombre del error | Causa | Solucionar |
---|---|---|
InvalidResourceType |
El elemento <ResourceURL> de la política SOAPMessageValidation se ha definido en un tipo de recurso que no admite la política.
|
build |
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.
|
build |
RootElementNameUnspecified |
El elemento <Element> de la política SOAPMessageValidation no contiene el nombre del elemento raíz. |
build |
InvalidRootElementName |
El elemento <Element> de la política SOAPMessageValidation contiene un nombre de elemento raíz que no cumple las reglas de XML para asignar nombres válidos a los elementos. |
build |
Esquemas
Cada tipo de política se define mediante un esquema XML (.xsd
). Puedes consultar los esquemas de políticas en GitHub.
Temas relacionados
- Política de protección contra amenazas XML
- Política de XML a JSON
- Política de JSON a XML
- JSON Threat Protection policy