Cette page a été traduite par l'API Cloud Translation.

Règle OASValidation

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

À propos de la stratégie OASValidation

La règle OASValidation (validation de spécification OpenAPI) vous permet de valider une requête ou un message de réponse entrants par rapport à une spécification OpenAPI 3.0 (JSON ou YAML). Consultez la section Quels contenus sont validés ?

La stratégie OASValidation spécifie le nom de la spécification OpenAPI à utiliser pour la validation lorsque l'étape à laquelle la stratégie est associée s'exécute. La spécification OpenAPI est stockée en tant que ressource dans l'emplacement standard suivant dans le groupe de proxys d'API : apiproxy/resources/oas. La spécification OpenAPI doit comporter l'extension .json, .yml ou .yaml.

Ajoutez une spécification OpenAPI en tant que ressource à un groupe de proxys d'API à l'aide de l'interface utilisateur ou de l'API, comme décrit dans Gérer les ressources.

Quel contenu est validé ?

Le tableau suivant récapitule le contenu du message de requête validé par la règle OASValidation, par composant.

Composants	Validation de requête
Basepath	Valide le chemin de base défini par le proxy d'API ; ignore le chemin de base spécifié dans la spécification OpenAPI.
Chemin	Vérifie que le chemin de la requête (moins le chemin de base) correspond à l'un des formats de chemin d'accès définis dans la spécification OpenAPI.
Verbe	Vérifie que le verbe est défini pour le chemin d'accès dans la spécification OpenAPI.
Corps du message de la requête	Vérifie l'existence du corps du message dans la requête, si nécessaire. Le cas échéant, vérifie le corps du message par rapport au schéma de corps de la requête de l'opération dans la spécification OpenAPI. Configurer cette option à l'aide de `<ValidateMessageBody>` Remarque : La règle valide un corps de message de requête par rapport à la spécification OpenAPI uniquement si Type de contenu est défini sur `application/json`. Si le type de contenu n'est pas défini sur `application/json`, la validation du corps du message de requête est automatiquement effectuée (sans valider le contenu).
Paramètres	Vérifie que les paramètres requis sont présents dans la requête, y compris les paramètres de chemin, d'en-tête, de requête et de cookie. Vérifie que les valeurs des paramètres correspondent à celles définies dans la spécification OpenAPI. Le cas échéant, vérifie s'il existe dans la requête des paramètres qui ne sont pas définis dans la spécification OpenAPI. Configurer cette option à l'aide de `<AllowUnspecifiedParameters>`

Le tableau suivant récapitule le contenu du message de réponse confirmé par la règle OASValidation, par composant.

Composants	Validation de la réponse
Chemin	Vérifie que le chemin de la requête (moins le chemin de base) correspond à l'un des formats de chemin d'accès définis dans la spécification OpenAPI.
Verbe	Vérifie que le verbe est défini pour le chemin d'accès dans la spécification OpenAPI.
Corps du message de la réponse	Vérifie l'existence du corps du message dans la réponse, si nécessaire. Vérifie que les en-têtes de réponse de la spécification OpenAPI sont présents dans le message de réponse, et que la valeur des en-têtes de réponse correspond au schéma. Le cas échéant, vérifie le corps du message par rapport au schéma de corps de la réponse de l'opération dans la spécification OpenAPI. Configurer cette option à l'aide de `<ValidateMessageBody>`

Exemples

Les exemples suivants montrent certaines manières d'utiliser la règle OASValidation pour valider les messages par rapport à une spécification OpenAPI 3.0.

Vérifier le message de requête

Dans l'exemple suivant, la règle myoaspolicy valide le corps du message de requête en fonction du schéma du corps du message de requête de l'opération défini dans la spécification OpenAPI my-spec.json.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Si le corps du message n'est pas conforme à la spécification OpenAPI, une erreur policies.oasvalidation.Failed est renvoyée.

Vérifier les paramètres

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête, de requête ou de cookie est spécifié dans la requête mais pas dans la spécification OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Élément `<OASValidation>`

Définit la règle de validation de la spécification OpenAPI.

Valeur par défaut	Consultez l'onglet Règles par défaut ci-dessous.
Requis ?	Obligatoire
Type	Objet complexe
Élément parent	N/A
Éléments enfants	`<DisplayName>` `<OASResource>` `<Source>` `<Options>` `<Source>`

Syntaxe

L'élément <OASValidation> utilise la syntaxe suivante :

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Règle par défaut

L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez une règle de validation OAS à votre flux dans l'interface utilisateur d'Apigee :

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
`name`	N/A	Obligatoire	Nom interne de la règle. La valeur de l'attribut `name` peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément `<DisplayName>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
`continueOnError`	faux	Facultatif	Défini sur "false" pour renvoyer une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Défini sur "true" pour que l'exécution du flux se poursuive même après l'échec d'une règle.
`enabled`	vrai	Facultatif	Défini sur "true" pour appliquer la règle. Défini 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.

Référence d'élément enfant

Cette section décrit les éléments enfants de <OASValidation>.

`<DisplayName>`

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Requis ?	Facultatif. Si vous omettez `<DisplayName>`, la valeur de l'attribut `name` de la règle est utilisée.
Type	Chaîne
Élément parent	<`PolicyElement`>
Éléments enfants	Aucune

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

`<OASResource>`

Spécifie la spécification OpenAPI par rapport à laquelle procéder à la validation. Vous pouvez stocker ce fichier :

Au niveau du champ d'application de proxy d'API sous /apiproxy/resources/oas dans le groupe de proxys d'API
Dans la section Resources de la vue du navigateur de l'éditeur de proxy d'API

Pour plus d'informations, consultez Gérer les ressources.

Vous pouvez spécifier la spécification OpenAPI à l'aide d'un modèle de message, tel que {oas.resource.url}. Dans ce cas, la valeur de la variable de flux oas.resource.url (entre accolades) est évaluée et remplacée par la chaîne de charge utile lors de l'exécution. Pour en savoir plus, consultez l'article Modèles de message.

Valeur par défaut	None
Requis ?	Obligatoire
Type	Chaîne
Élément parent	`<OASValidation>`
Éléments enfants	Aucun

Syntaxe

L'élément <OASResource> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Exemple

L'exemple suivant fait référence à la spécification my-spec.yaml stockée sous /apiproxy/resources/oas dans le groupe de proxys d'API :

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

L'élément <OASResource> ne comporte aucun attribut ni élément enfant.

<Options>

Permet de configurer les options de la stratégie.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<OASValidation>`
Éléments enfants	`<ValidateMessageBody>` `<AllowUnspecifiedParameters>`

Syntaxe

L'élément <Options> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant configure les options de la stratégie. Chacune des options est décrite plus en détail ci-dessous.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

Spécifie si la stratégie doit valider le corps du message par rapport au schéma du corps de la requête de l'opération dans la spécification OpenAPI. Définissez la valeur sur true pour valider le contenu du corps du message. Définissez la valeur sur false pour confirmer que le corps du message existe.

Vous pouvez vérifier si l'exécution du flux continue après une erreur de validation en définissant l'attribut continueOnError de l'élément <OASValidation> sur true.

Remarque : La règle valide un corps de message de requête par rapport à la spécification OpenAPI uniquement si type de contenu est défini sur application/json. Si le type de contenu n'est pas défini sur application/json, la validation du corps du message de requête réussit automatiquement (sans valider le contenu).

Valeur par défaut	faux
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	`<Options>`
Éléments enfants	Aucun

Syntaxe

L'élément <ValidateMessageBody> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant active la validation du contenu du corps du message :

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

`<AllowUnspecifiedParameters>`

Configure le comportement de la stratégie si des paramètres d'en-tête, de requête ou de cookie sont présents dans la requête et non définis dans la spécification OpenAPI.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	`<Options>`
Éléments enfants	`<Header>` `<Query>` `<Cookie>`

Syntaxe

L'élément <AllowUnspecifiedParameters> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête, de requête ou de cookie est spécifié dans la requête mais pas dans la spécification OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Configure le comportement de la règle si la requête contient des paramètres de cookie qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres d'en-tête dans la requête qui ne sont pas définis dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	vrai
Requis ?	Boolean
Type	Type complexe
Élément parent	`<AllowUnspecifiedParameters>`
Éléments enfants	Aucun

Syntaxe

L'élément <Header> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (enfant de <AllowUnspecifiedParameters>)

Configure le comportement de la règle si la requête contient des paramètres de requête qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres de requête dans la requête qui ne sont pas définies dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	vrai
Requis ?	Boolean
Type	Type complexe
Élément parent	`<AllowUnspecifiedParameters>`
Éléments enfants	Aucun

Syntaxe

L'élément <Query> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre de requête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Configure le comportement de la règle si la requête contient des paramètres de cookie qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres de cookies dans la requête qui ne sont pas définis dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	vrai
Requis ?	Boolean
Type	Type complexe
Élément parent	`<AllowUnspecifiedParameters>`
Éléments enfants	Aucun

Syntaxe

L'élément <Cookie> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre de requête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

`<Source>`

Message JSON à évaluer par rapport aux attaques contre les charges utiles JSON. Ce paramètre est habituellement défini sur request, car vous devez généralement évaluer les requêtes entrantes provenant des applications clientes. Définissez la valeur sur response pour évaluer les messages de réponse. Définissez la valeur sur message pour évaluer automatiquement le message de requête lorsque la stratégie est associée au flux de la requête et au message de réponse lorsque la stratégie est associée au flux de réponse.

Valeur par défaut	requête
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	`<Source>`
Éléments enfants	Aucun

Syntaxe

L'élément <Source> utilise la syntaxe suivante :

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Exemple

L'exemple suivant évalue automatiquement le message de requête lorsque la règle est associée au flux de la requête et le message de réponse lorsque la règle est associée au flux de réponse :

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

L'élément <Source> ne comporte aucun attribut ni élément enfant.

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.

Codes d'erreur

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur	État HTTP	Cause
`steps.oasvalidation.Failed`	500	Le corps du message de la requête ne peut pas être validé par rapport à la spécification OpenAPI fournie.
`steps.oasvalidation.SourceMessageNotAvailable`	500	La variable spécifiée dans l'élément `<Source>` de la règle ne relève pas du champ d'application ou ne peut pas être résolue.
`steps.oasvalidation.NotMessageVariable`	500	L'élément `<Source>` est défini sur une variable qui n'est pas de type message.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur	Cause
`ResourceDoesNotExist`	La spécification OpenAPI référencée dans l'élément `<OASResource>` n'existe pas.
`ResourceCompileFailed`	La spécification OpenAPI incluse dans le déploiement contient des erreurs qui empêchent sa compilation. Cela indique généralement que la spécification n'est pas une spécification OpenAPI 3.0 correctement formulée.
`BadResourceURL`	La spécification OpenAPI référencée dans l'élément `<OASResource>` ne peut pas être traitée. Cela peut se produire si le fichier n'est pas un fichier JSON ou YAML, ou si l'URL du fichier n'est pas spécifiée correctement.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Où :	Exemple
`fault.name="fault_name"`	`fault_name` est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	`fault.name Matches "ResourceDoesNotExist"`
`oasvalidation.policy_name.failed`	`policy_name` est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	`oasvalidation.myoaspolicy.failed = true`

Fonctionnalités des spécifications OpenAPI compatibles

La règle OASValidation accepte les fonctionnalités de spécification OpenAPI récapitulées dans le tableau suivant, par catégorie. Les fonctionnalités non compatibles sont également répertoriées.

Catégorie	Compatible	Incompatible
Formats de types de données	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
Objet discriminateur	mapping propertyName	ND
Objet de type de contenu	schema	encoding example examples
Objet opérations	parameters requestBody responses security (partial support)	callbacks deprecated servers
Objet paramètres	allowEmptyValue dans (`query`, `header`, `path`) required responses schema style (`deepObject`, `form`, `formmatrix`, `label`, `pipeDelimited`, `simple`, `spaceDelimited`) Remarque : `deepObject` ne prend en charge que les paramètres de chaîne ; les tableaux et les objets imbriqués ne sont pas compatibles.	allowReserved deprecated example examples content
Objet chemins	delete get head options parameters patch post put trace variables	servers
Objet corps de la requête	application/json application/hal+json application/x-www-form-urlencoded (objet `encoding` non compatible) content required	application/xml multipart/form-data text/plain text/xml
Objet réponse	application/json application/hal+json application/x-www-form-urlencoded (objet `encoding` non compatible) content headers	application/xml links text/plain text/xml
Objet réponses	default Code d'état HTTP	ND
Objet schéma	$ref additionalProperties (variante d'option booléenne uniquement) allOf (ignored if `additionalProperties` is `false`) anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems	deprecated example readOnly writeOnly xml
Objet schéma de sécurité	dans (`header`, `query`) (ignoré si `type` est `http`) name type (`apiKey`, `http`)	bearerFormat flows openIdConnectUrl scheme
Objet serveur	url variables	Définition de plusieurs serveurs

Règle OASValidation

À propos de la stratégie OASValidation

Quel contenu est validé ?

Exemples

Vérifier le message de requête

Vérifier les paramètres

Élément <OASValidation>

Syntaxe

Règle par défaut

Référence d'élément enfant

<DisplayName>

Syntaxe

Exemple

<OASResource>

Syntaxe

Exemple

<Options>

Syntaxe

Exemple

<ValidateMessageBody>

Syntaxe

Exemple

<AllowUnspecifiedParameters>

Syntaxe

Exemple

Syntaxe

Exemple

Syntaxe

Exemple

Syntaxe

Exemple

<Source>

Syntaxe

Exemple

Schémas

Codes d'erreur

Erreurs d'exécution

Erreurs de déploiement

Variables de panne

Fonctionnalités des spécifications OpenAPI compatibles

Articles associés

Élément `<OASValidation>`

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`