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 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 De forma opcional, usa el elemento |
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.
- 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>
- Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo de tu extremo de proxy:
- Especifica la ubicación de tu archivo de recursos XSD con el elemento
<ResourceURL>
. Por ejemplo:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- 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>
- Especifica la ubicación de tu archivo de recursos XSD con el elemento
- 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ó comoapplication/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.
- Crea un archivo de recursos WSDL nuevo. Por ejemplo, “example-wsdl.wsdl”:
- Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo del extremo del proxy:
- 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"/> ...
- 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. - 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>
- Configura el atributo
- 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:
- Agrega la política de validación de mensajes SOAP al flujo de procesamiento previo del extremo del proxy:
- 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>
- 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ó comoapplication/json
.Para comprobar si hay un formato correcto en un archivo XML, usa XML como carga útil del mensaje y configura
Content-type
comoapplication/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:
|
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
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Este error ocurre si el elemento Las variables del tipo de mensaje representan respuestas y solicitudes HTTP completas. Las variables de flujo integradas de Apigee |
build |
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. | build |
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.
|
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> en la política SOAPMessageValidation no contiene el nombre del elemento raíz. |
build |
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. |
build |
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
- Política de protección contra amenazas de XML
- Política de XML a JSON
- Política de JSON a XML
- Política de protección contra amenazas de JSON