Règle OASValidation

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

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

This element has the following attributes that are common to all policies:

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

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

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

The <DisplayName> element uses the following syntax:

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

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

The <DisplayName> element has no attributes or child elements.

<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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

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