Règle OASValidation

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

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

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

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.

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

<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.

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

<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 :

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.

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

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

<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.

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

<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.

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

<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.

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

<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.

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

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

<Header> (enfant de <AllowUnspecifiedParameters>)

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.

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

<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.

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

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

<Cookie> (enfant de <AllowUnspecifiedParameters>)

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.

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

<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.

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

<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.

Erreurs de déploiement

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

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.

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.

Articles associés

• Règle de protection contre les menaces JSON
• Règle SOAPMessageValidation