Ajout de la validation des demandes aux déploiements d'API

Découvrez comment empêcher l'envoi de demandes non valides aux services back-end en validant les demandes entrantes par rapport à une stratégie de demande de validation avec API Gateway.

En règle générale, vous voulez éviter de placer une charge inutile sur les services back-end en envoyant uniquement des demandes valides à ces services. Pour empêcher l'envoi de demandes non valides aux services back-end, vous pouvez utiliser une passerelle d'API pour valider les demandes entrantes par rapport à une stratégie de demande de validation. Si une demande ne répond pas aux exigences de la stratégie de validation, vous pouvez configurer la passerelle d'API pour qu'elle rejette la demande au lieu de la transmettre au service back-end ciblé. A la place, la passerelle d'API envoie une réponse de code d'erreur 4xx au client d'API qui a envoyé la demande.

A l'aide d'une passerelle d'API, vous pouvez configurer des stratégies de demande de validation pour vérifier les points suivants :

la demande inclut des en-têtes spécifiques
la demande inclut des paramètres de requête spécifiques
le corps de demande est d'un type de contenu spécifique

Vous pouvez contrôler la façon dont une passerelle d'API applique une stratégie de demande de validation en indiquant un mode de validation pour la stratégie :

En mode Mise en application, la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end. La passerelle d'API n'envoie pas de demandes dont la validation échoue au service back-end. La passerelle d'API envoie une réponse de code d'erreur 4xx à un client d'API en envoyant une demande dont la validation échoue. La passerelle d'API inclut des entrées dans les journaux d'exécution pour les erreurs de validation.
En mode permissif, la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou non la validation. Notez que les demandes qui échouent à la validation sont toujours envoyées au service back-end. La passerelle d'API inclut des entrées dans les journaux d'exécution pour les erreurs de validation. Utilisez le mode Permissive pour évaluer l'impact probable de l'application d'une stratégie de demande de validation à un système déjà dans le système de production, sans affecter les clients API qui envoient actuellement des demandes.
En mode Désactivé, la passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.

La passerelle d'API applique les stratégies de demande de validation après les stratégies de demande CORS et après les stratégies de demande d'authentification et d'autorisation, mais avant les stratégies de demande de transformation.

Vous pouvez ajouter des stratégies de demande de validation à une spécification de déploiement d'API en :

utilisant la console,
modifiant un fichier JSON.

Utilisation de la console pour ajouter des stratégies de demande de validation

Pour ajouter des stratégies de demande de validation à une spécification de déploiement d'API à l'aide de la console, procédez comme suit :

Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option Entièrement nouveau, puis saisissez les détails sur la page Informations de base.

Pour plus d'informations, reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et à Mise à jour d'une passerelle d'API.
Sélectionnez Suivant et indiquez les options d'authentification sur la page Authentification.

Pour plus d'informations sur les options d'authentification, reportez-vous à Ajout de l'authentification et de l'autorisation aux déploiements d'API.
Sélectionnez Suivant et saisissez les détails de chaque routage dans le déploiement d'API sur la page Routages.
Sur la page Itinéraires, sélectionnez le routage pour lequel spécifier des stratégies de demande de validation.
Sélectionnez Afficher les stratégies de demande de routage.
Pour valider les en-têtes inclus dans une demande à la passerelle d'API pour le routage en cours, créez une stratégie de demande de validation d'en-tête :
1. Cliquez sur le bouton Ajouter en regard de Validations d'en-tête et indiquez les détails du premier en-tête de la demande à valider :
  - Nom d'en-tête : nom d'un en-tête dans la demande à valider. Par exemple, X-Username .
  - Obligatoire : indique si l'en-tête que vous avez spécifié doit être présent dans la demande pour que la demande soit considérée comme valide.
2. (Facultatif) Sélectionnez Autre en-tête et indiquez des en-têtes supplémentaires dans la demande à valider.
3. Sélectionnez Afficher les options avancées et sélectionnez un mode pour indiquer comment la stratégie de demande de validation d'en-tête est appliquée :
  - Application : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - Autorisé : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou échouent à la validation.
  - Désactivé : la passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Notez que Imposer est le mode de validation par défaut.
4. Sélectionnez Ajouter des validations.
Pour valider les paramètres de requête inclus dans une demande à la passerelle d'API pour le routage en cours, créez une stratégie de demande de validation de paramètre de requête :
1. Cliquez sur le bouton Ajouter en regard de Validations de paramètre de requête et indiquez les détails du premier paramètre de requête dans la demande à valider :
  - Nom du paramètre : nom d'un paramètre de requête dans la demande à valider. Par exemple, state.
  - Obligatoire : indique si le paramètre de requête que vous avez spécifié doit être présent dans la demande pour que la demande soit considérée comme valide.
2. (Facultatif) Sélectionnez Autre paramètre et indiquez des paramètres de requête supplémentaires dans la demande à valider.
3. Sélectionnez Afficher les options avancées et sélectionnez un mode pour indiquer comment la stratégie de demande de validation de paramètre de requête est appliquée :
  - Application : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - Autorisé : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou échouent à la validation.
  - Désactivé : la passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Notez que Imposer est le mode de validation par défaut.
4. Sélectionnez Ajouter des validations.
Pour valider le contenu dans le corps d'une demande à la passerelle d'API pour le routage en cours, créez une stratégie de demande de validation de corps :
1. Sélectionnez le bouton Ajouter en regard de Validation du corps et indiquez les éléments suivants :
  - Obligatoire : indique si le corps d'une demande doit être l'un des types de contenu que vous indiquez pour que la demande soit considérée comme valide.
  - Type de support : type de contenu valide pour le corps d'une demande. Par exemple, application/json, application/xml.
2. (Facultatif) Sélectionnez Autre type de média et indiquez des types de contenu valides supplémentaires pour le corps de la demande.
  Si vous spécifiez plusieurs types de contenu, le corps de la demande doit être l'un des types de contenu autorisés que vous spécifiez pour que la demande soit considérée comme valide.
3. Sélectionnez Afficher les options avancées et sélectionnez un mode pour indiquer comment la stratégie de demande de validation de corps est appliquée :
  - Application : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - Autorisé : la passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou échouent à la validation.
  - Désactivé : la passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Notez que Imposer est le mode de validation par défaut.
4. Sélectionnez Ajouter des validations.
Sélectionnez Suivant pour vérifier les détails saisis pour les routages.
Sélectionnez Créer ou Enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
(Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).

Modification d'un fichier JSON pour ajouter des stratégies de demande de validation

Pour ajouter des stratégies de demande de validation à une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :

A l'aide de l'éditeur JSON de votre choix, modifiez la spécification de déploiement d'API existante à laquelle ajouter des stratégies de demande de validation ou créez une spécification de déploiement d'API (reportez-vous à Création d'une spécification de déploiement d'API).

Par exemple, la spécification de déploiement d'API de base suivante définit une fonction simple sans serveur Hello World dans OCI Functions en tant que back-end unique :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Insérez une section requestPolicies après la section backend du routage auquel appliquer la stratégie de demande de validation. Par exemple :

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

Afin de valider les en-têtes inclus dans une demande à la passerelle d'API pour le routage en cours, indiquez une stratégie de demande de validation headerValidations :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "<header-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
où :
- "name":"<header-name>" est un en-tête de la demande de validation. Le nom que vous indiquez n'est pas sensible à la casse. Par exemple, X-Username.
- "required": <true|false> indique si l'en-tête indiqué par "name":"<header-name>" doit être présent dans la demande pour que la demande soit considérée comme valide.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indique comment la passerelle d'API valide les demandes par rapport à la stratégie de demande de validation d'en-tête, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou non la validation.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Par exemple, "validationMode": "PERMISSIVE". ENFORCING est utilisé comme mode de validation par défaut si vous n'incluez pas "validationMode".
Par exemple :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "X-Username",
            "required": true
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
Dans cet exemple, pour que la demande soit considérée comme valide, elle doit inclure l'en-tête X-Username. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
Afin de valider les paramètres de requête inclus dans une demande à la passerelle d'API pour le routage en cours, indiquez une stratégie de demande de validation queryParameterValidations :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "<query-parameter-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
où :
- "name":"<query-parameter-name>" est un paramètre de requête dans la demande à valider. Le nom que vous indiquez n'est pas sensible à la casse. Par exemple, state.
- "required": <true|false> indique si le paramètre de requête indiqué par "name":"<query-parameter-name>" doit être présent dans la demande pour que la demande soit considérée comme valide.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indique comment la passerelle d'API valide les demandes par rapport à la stratégie de demande de validation de paramètre de requête, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou non la validation.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Par exemple, "validationMode": "PERMISSIVE". ENFORCING est utilisé comme mode de validation par défaut si vous n'incluez pas "validationMode".
Par exemple :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "state",
            "required": false
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
Dans cet exemple, pour que la demande soit considérée comme valide, elle peut éventuellement inclure le paramètre de requête state. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
Afin de valider le contenu dans le corps d'une demande à la passerelle d'API pour le routage en cours, indiquez une stratégie de demande de validation bodyValidation :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "<media-type-1>": {
              "validationType": "NONE"
            },
            "<media-type-2>": {
              "validationType": "NONE"
            }            
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
où :
- "required": true indique que le type de contenu du corps de demande doit être l'un des types de contenu indiqués.
- "content": {"<media-type-1>": {"validationType": "NONE"}, "<media-type-2>": {"validationType": "NONE"}} indique des types de contenu autorisés pour le corps de la demande. Le corps de la demande doit être l'un des types de contenu que vous spécifiez. Par exemple, application/json, application/xml. Seule NONE est actuellement prise en charge pour "validationType".
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indique comment la passerelle d'API valide les demandes par rapport à la stratégie de demande de validation de corps, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end, qu'elles réussissent ou non la validation.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la stratégie de demande de validation. La passerelle d'API envoie toutes les demandes au service back-end.
  Par exemple, "validationMode": "PERMISSIVE". ENFORCING est utilisé comme mode de validation par défaut si vous n'incluez pas "validationMode".
Par exemple :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "application/json": {
              "validationType": "NONE"
            },
            "application/xml": {
              "validationType": "NONE"
            }
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
Dans cet exemple, pour que la demande soit considérée comme valide, le type de contenu du corps de la demande doit être application/json ou application/xml. La passerelle d'API envoie uniquement les demandes qui passent la validation au service back-end.
Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
Utilisez la spécification de déploiement d'API lorsque vous créez ou mettez à jour un déploiement d'API en :
- spécifiant le fichier JSON dans la console lorsque vous sélectionnez l'option Télécharger une API existante,
- spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.
Pour plus d'informations, reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et à Mise à jour d'une passerelle d'API.
(Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).

Documentation Oracle Cloud Infrastructure

Ajout de la validation des demandes aux déploiements d'API

Utilisation de la console pour ajouter des stratégies de demande de validation

Modification d'un fichier JSON pour ajouter des stratégies de demande de validation