Règle OASValidation

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

icône de la règle

À 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 ND 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é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.

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 ND
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 None

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 None

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.

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

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 None

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 None

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 None

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 None

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 et les variables d'erreur définies par Apigee lorsque cette règle 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 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 est hors 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 formé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

Articles associés