Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'
Apigee Edge.
La règle SOAPMessageValidation effectue les opérations suivantes :
- Valide tout message XML par rapport à son schéma XSD.
- Valide les messages SOAP par rapport à une définition WSDL.
- Détermine le bon format des messages JSON et XML.
Bien que le nom de cette règle dans l'interface utilisateur soit SOAPMessageValidation, la règle valide plus que des messages SOAP. Cette section fait référence à la règle en tant que règle MessageValidation.
La validation des messages offre les avantages suivants :
- Informe immédiatement les développeurs d'applications qui utilisent votre API si leurs requêtes sont non conformes ou incomplètes.
- Identifie les problèmes dans les requêtes, tels que les balises XML qui ne sont pas correctement fermées.
- Protège les services de backend en bloquant les messages XML ou SOAP comportant des structures susceptibles de provoquer un comportement imprévisible.
- Réduit le temps passé à dépanner, rechercher sur des forums ou consulter le support technique.
- Encourage les développeurs à se familiariser avec la définition WSDL du schéma XML afin d'éliminer les erreurs de validation, faisant des schémas XML bien compris un composant clé de la documentation de votre API.
Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.
Vidéos
Regardez les vidéos suivantes pour en savoir plus sur la règle MessageValidation :
| Vidéo | Description |
|---|---|
| Valider la requête XML | Validez la requête XML pour une API à l'aide de la règle MessageValidation. |
| Valider la requête JSON | Validez la requête JSON pour une API à l'aide de la règle MessageValidation. |
Élément <MessageValidation>
Définit la règle MessageValidation.
| Valeur par défaut | Consultez l'onglet Règles par défaut ci-dessous. |
| Obligatoire ? | Facultatif |
| Type | Objet complexe |
| Élément parent | Non disponible |
| Éléments enfants |
<DisplayName><Element><ResourceURL><SOAPMessage><Source> |
Syntaxe
L'élément <MessageValidation> utilise la syntaxe suivante :
<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>Règle par défaut
L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez une règle MessageValidation à votre flux dans l'interface utilisateur d'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>
Cet élément possède les attributs suivants qui sont communs à toutes les règles :
| Attribut | Par défaut | Obligatoire ? | Description |
|---|---|---|---|
name |
ND | Obligatoire |
Nom interne de la règle. La valeur de l'attribut Vous pouvez également utiliser l'élément |
continueOnError |
faux | Facultatif | Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
|
enabled |
true | Facultatif | Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux. |
async |
faux | Obsolète | Cet attribut est obsolète. |
Exemples
Les exemples suivants illustrent certaines des manières d'utiliser la règle MessageValidation :
1 : Validation XSD
Vous pouvez utiliser la règle de validation de message pour valider la charge utile d'une requête de message XML par rapport à un schéma XSD.
- Créez un fichier de ressources XSD. Par exemple,
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>
- Ajoutez la règle de validation de message SOAP au flux préliminaire de votre point de terminaison de proxy :
- Spécifiez l'emplacement de votre fichier de ressources XSD à l'aide de l'élément
<ResourceURL>. Exemple :... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- Supprimez les éléments
<SOAPMessage>et<Element>de la définition de règle.
Votre définition de règle devrait ressembler à ceci :
<MessageValidation continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My XML Validator</DisplayName> <Properties/> <Source>request</Source> <ResourceURL>xsd://note-schema.xsd</ResourceURL> </MessageValidation> - Spécifiez l'emplacement de votre fichier de ressources XSD à l'aide de l'élément
- Envoyez une requête
POSTà votre proxy d'API avec votre XML comme charge utile du message, comme le montre l'exemple suivant :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>'
Notez que l'en-tête
Content-typeest défini surapplication/xml.Vous pouvez également créer un fichier de données pour la charge utile et le référencer avec une commande semblable à celle-ci :
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/note-payload.xml'
Vous devriez recevoir une réponse HTTP 200. Selon votre point de terminaison cible, vous pouvez recevoir des détails supplémentaires sur la requête. Par exemple, si vous utilisez http://httpbin.org/post comme point de terminaison cible et que vous spécifiez la sortie -v (verbose), la réponse doit ressembler à ce qui suit :
< 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" }
Pour vérifier que votre validation XSD fonctionne, essayez d'insérer un autre tag dans le corps de votre requête. Exemple :
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>'
Vous devriez recevoir une erreur de validation.
2 : Validation SOAP
Vous pouvez utiliser la règle de validation de message pour valider la charge utile d'une requête de message SOAP par rapport à un WSDL.
- Créez un fichier de ressources WSDL. Par exemple, "example-wsdl.wsdl" :
- Ajoutez la règle de validation de message SOAP au flux préliminaire de votre point de terminaison de proxy :
- Définissez l'attribut
versionde l'élément<SOAPMessage>sur la version du protocole SOAP par rapport auquel vous souhaitez effectuer la validation. Par exemple, "1.1" :... <SOAPMessage version="1.1"/> ...
- Définissez la valeur de l'élément
<Element>sur l'élément par rapport auquel vous souhaitez effectuer la validation :... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>spécifie le premier enfant sous l'élément<Body>de l'enveloppe de la requête SOAP.Définissez l'attribut
namespacesur l'espace de noms de cet enfant. - Spécifiez l'emplacement de votre fichier de ressources WSDL avec l'élément
<ResourceURL>. Exemple :... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
Votre définition de règle devrait ressembler à ceci :
<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> - Définissez l'attribut
- Envoyez une requête
POSTà votre proxy d'API avec l'enveloppe SOAP comme charge utile du message, comme le montre l'exemple suivant :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>'
Notez que l'en-tête
Content-typeest défini sur "application/xml".Vous pouvez également créer un fichier de données pour la charge utile et le référencer avec une commande semblable à celle-ci :
curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock --data '@../examples/soap-payload.xml'
Vous devriez recevoir une réponse HTTP 200. Selon votre point de terminaison cible, vous pouvez recevoir des détails supplémentaires sur la requête. Par exemple, si vous utilisez http://httpbin.org/post comme point de terminaison cible, la réponse doit ressembler à ce qui suit :
< 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 bien formé
Vous pouvez utiliser la règle de validation de message pour confirmer qu'une charge utile de message JSON ou XML est correctement formée (diffère de la validation). La règle garantit que la structure et le contenu sont conformes aux normes acceptées, y compris :
- Il existe un seul élément racine.
- Il n'y a pas de caractères non autorisés dans le contenu.
- Les objets et les tags sont correctement imbriqués.
- Les tags de début et de fin correspondent.
Pour rechercher une charge utile XML ou JSON bien formée, procédez comme suit :
- Ajoutez la règle de validation de message SOAP au flux préliminaire de votre point de terminaison de proxy.
- Supprimez les éléments
<ResourceURL>,<SOAPMessage>et<Element>de la définition de règle.Votre définition de règle devrait ressembler à ceci :
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation> - Envoyez une requête
POSTà votre proxy d'API, comme le montre l'exemple suivant :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." } }'Notez que l'en-tête
Content-typeest défini surapplication/json.Pour vérifier que le fichier XML est bien formé, utilisez XML comme charge utile du message et définissez
Content-typesurapplication/xml.
Vous devriez recevoir une réponse HTTP 200. Lorsque vous envoyez une charge utile de message qui ne contient pas de fichier XML ou JSON correctement formaté, vous devez recevoir une erreur steps.messagevalidation.Failed.
Référence d'élément enfant
Cette section décrit les éléments enfants de <MessageValidation>.
<DisplayName>
Use in addition to the name attribute to label the policy in the
management UI proxy editor with a different, more natural-sounding name.
The <DisplayName> element is common to all policies.
| Default Value | N/A |
| Required? | Optional. If you omit <DisplayName>, the value of the
policy's name attribute is used. |
| Type | String |
| Parent Element | <PolicyElement> |
| Child Elements | None |
The <DisplayName> element uses the following syntax:
Syntax
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Example
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
The <DisplayName> element has no attributes or child elements.
<Element>
Spécifie l'élément dans le message à valider. Il s'agit du premier enfant sous l'élément <Body> dans l'enveloppe de la requête SOAP.
| Valeur par défaut | sampleObject |
| Obligatoire ? | Facultatif |
| Type | Chaîne |
| Élément parent |
<MessageValidation>
|
| Éléments enfants | Aucun |
L'élément <Element> utilise la syntaxe suivante :
Syntaxe
... <Element namespace="element_namespace">element_to_validate</Element> ...
Exemple 1
L'exemple suivant définit un seul élément à valider :
... <Element namespace="https://example.com/gateway">getID</Element> ...
Exemple 2
Vous pouvez spécifier plusieurs éléments à valider en ajoutant plusieurs éléments <Element> :
... <Element namespace="https://example.com/gateway">getID</Element> <Element namespace="https://example.com/gateway">getDetails</Element> ...
L'élément <Element> possède les attributs suivants :
| Attribut | Par défaut | Obligatoire ? | Description |
|---|---|---|---|
namespace |
"http://sample.com" | Facultatif | Définit l'espace de noms de l'élément à valider. |
<ResourceURL>
Identifie le schéma XSD ou la définition WSDL à utiliser pour valider le message source.
| Valeur par défaut | wsdl://display_name.wsdl |
| Obligatoire ? | Facultatif |
| Type | Chaîne |
| Élément parent |
<MessageValidation>
|
| Éléments enfants | Aucun |
L'élément <ResourceURL> utilise la syntaxe suivante :
Syntaxe
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Exemples
Pour un fichier XML :
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
Pour un fichier WSDL :
... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
La valeur de <ResourceURL> doit pointer vers un fichier de ressources dans votre proxy d'API. Cet élément ne peut pas faire référence à des ressources externes via HTTP ou HTTPS.
Si vous ne spécifiez pas de valeur pour <ResourceURL>, le message est vérifié pour déterminer si le format JSON ou XML bien formé si l'en-tête Content-type est application/json ou
application/xml, respectivement.
L'élément <ResourceURL> n'a pas d'éléments enfants ni d'attributs.
Utiliser des fichiers XSD pour la validation
Si la charge utile XML que vous validez avec la règle MessageValidation fait référence à un autre schéma, vous devez ajouter au fichier XSD inclus le préfixe xsd dans l'attribut schemaLocation.
L'exemple de schéma suivant est composé de plusieurs fichiers 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>
Utiliser des fichiers WSDL pour la validation
Un fichier WSDL doit définir au moins un schéma. S'il ne fait pas référence à au moins un schéma, la règle MessageValidation échoue.
La profondeur maximale d'importation pour un schéma est de 10. Si vous dépassez ce nombre d'importations imbriquées, la règle MessageValidation échoue.
<SOAPMessage>
Définit la version SOAP par rapport à laquelle la règle MessageValidation procède à la validation.
| Valeur par défaut | N/A |
| Obligatoire ? | Facultatif |
| Type | n/a |
| Élément parent |
<MessageValidation>
|
| Éléments enfants | Aucun |
L'élément <SOAPMessage> utilise la syntaxe suivante :
Syntaxe
... <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/> ...
Exemple
... <SOAPMessage version="1.1"/> ...
L'élément <SOAPMessage> possède les attributs suivants :
| Attribut | Par défaut | Obligatoire ? | Description |
|---|---|---|---|
version |
Aucune | Facultatif | Version SOAP utilisée par cette règle pour valider les messages SOAP. Les valeurs possibles sont les suivantes :
|
Pour plus d'informations, voir De la version SOAP 1.1 à la version SOAP 1.2 en 9 points.
<Source>
Identifie le message source à valider. La valeur de cet élément correspond au nom du message que vous souhaitez valider.
Si vous ne définissez pas <Source>, cette règle est définie par défaut sur message, qui fait référence au message de requête complet (dans un flux de requête) ou au message de réponse (dans un flux de réponse), y compris les charges utiles. Vous pouvez également le définir explicitement sur request ou response pour faire référence à la requête ou à la réponse.
| Valeur par défaut | requête |
| Obligatoire ? | Facultatif |
| Type | Chaîne |
| Élément parent |
<MessageValidation>
|
| Éléments enfants | Aucun |
L'élément <Source> utilise la syntaxe suivante :
Syntaxe
... <Source>message_to_validate</Source> ...
Exemple
... <Source>request</Source> ...
En plus de message, request et response, vous pouvez définir <Source> sur le nom d'un message de votre flux. Dans ce cas, vous devez toutefois créer un message personnalisé portant ce nom dans votre flux avant que cette règle ne s'exécute. Sinon, vous obtiendrez une erreur.
Si la valeur de <Source> ne peut pas être résolue dans le flux de messages ou est résolue dans un type non-message, l'un des événements suivants se produit :
- Si valeur NULL : Apigee génère une erreur
steps.messagevalidation.SourceMessageNotAvailable. - Si type non-message : Apigee génère une erreur
steps.messagevalidation.NonMessageVariable.
L'élément <Source> ne comporte aucun attribut ni élément enfant.
Codes d'erreur
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
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
This error occurs if the Message type variables represent entire HTTP requests and responses. The built-in Apigee
flow variables |
build |
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. | build |
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.
|
build |
ResourceCompileFailed |
The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation
policy contains an error that prevents it from compiling.
|
build |
RootElementNameUnspecified |
The <Element> element in the SOAPMessageValidation policy does not contain the root
element's name. |
build |
InvalidRootElementName |
The <Element> element in the SOAPMessageValidation policy contains a root element name
that does not adhere to XML rules for valid element naming. |
build |
Schémas
Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.
Articles associés
- Règle de protection contre les menaces XML
- Règle XML vers JSON
- Règle JSON vers XML
- Règle de protection contre les menaces JSON