Ajout de la validation de demande aux déploiements d'API

Découvrez comment empêcher l'envoi de demandes non valides aux services dorsaux, en validant les demandes entrantes par rapport à une politique de demande de validation avec la passerelle d'API.

En général, vous voulez éviter de charger inutilement les services back-end en envoyant uniquement des demandes valides à ces services. Pour empêcher l'envoi de demandes non valides aux services dorsaux, vous pouvez utiliser une passerelle d'API pour valider les demandes entrantes par rapport à une politique de demande de validation. Si une demande ne répond pas aux exigences de la politique de validation, vous pouvez configurer la passerelle d'API pour rejeter la demande au lieu de la transmettre au service dorsal ciblé. À la place, la passerelle d'API envoie une réponse de code d'erreur 4xx au client d'API qui a envoyé la demande.

À l'aide d'une passerelle d'API, vous pouvez configurer des politiques de demande de validation pour vérifier que :

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

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

En mode d'application, la passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal. La passerelle d'API n'envoie pas les demandes dont la validation échoue au service dorsal. La passerelle d'API envoie une réponse de code d'erreur 4xx à un client d'API envoyant une demande qui échoue à la validation. 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 politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non. Notez que les demandes dont la validation échoue sont toujours envoyées au service dorsal. 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 politique de demande de validation à un système déjà en 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 politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.

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

Vous pouvez ajouter des politiques de demande de validation à une spécification de déploiement d'API comme suit :

En utilisant la console.
En modifiant un fichier JSON.

Utilisation de la console pour ajouter des politiques de demande de validation

Pour ajouter des politiques de demande de validation à une spécification de déploiement d'API à l'aide de la console :

Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option À partir de zéro et entrez les détails dans la page Informations de base.

Pour plus d'informations, voir 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 spécifiez les options d'authentification dans la page Authentification.

Pour plus d'informations sur les options d'authentification, voir Ajout de l'authentification et de l'autorisation aux déploiements d'API.
Sélectionnez Suivant et entrez les détails des routes individuelles du déploiement d'API dans la page Routes.
Dans la page Routes, sélectionnez la route pour laquelle vous voulez spécifier des politiques de demande de validation.
Sélectionnez Afficher les politiques de demande de routage.
Pour valider les en-têtes inclus dans une demande à la passerelle d'API pour la route courante en créant une politique de demande de validation d'en-tête :
1. Sélectionnez le bouton Ajouter à côté de Validations d'en-tête et spécifiez 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 de validation. 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 Un autre en-tête et spécifiez des en-têtes supplémentaires dans la demande à valider.
3. Sélectionnez Afficher les options avancées et sélectionnez un mode pour spécifier comment la politique de demande de validation d'en-tête est appliquée :
  - Application : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - Permissif : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - Désactivé : La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Notez que le mode de validation par défaut est Application.
4. Sélectionnez Ajouter des validations.
Pour valider les paramètres d'interrogation inclus dans une demande à la passerelle d'API pour la route courante en créant une politique de demande de validation de paramètre d'interrogation :
1. Sélectionnez le bouton Ajouter à côté de Validations des paramètres d'interrogation et spécifiez les détails du premier paramètre d'interrogation de la demande à valider :
  - Nom du paramètre : Nom d'un paramètre d'interrogation dans la demande à valider. Par exemple, state .
  - Obligatoire : Indique si le paramètre d'interrogation 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 Un autre paramètre et spécifiez des paramètres d'interrogation supplémentaires dans la demande à valider.
3. Sélectionnez Afficher les options avancées et sélectionnez un mode pour spécifier comment la politique de demande de validation de paramètre d'interrogation est appliquée :
  - Application : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - Permissif : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - Désactivé : La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Notez que le mode de validation par défaut est Application.
4. Sélectionnez Ajouter des validations.
Pour valider le contenu du corps d'une demande à la passerelle d'API pour la route courante en créant une politique de demande de validation de corps :
1. Sélectionnez le bouton Ajouter à côté de Validation du corps et spécifiez :
  - Obligatoire : Indique si le corps d'une demande doit être l'un des types de contenu que vous spécifiez pour que la demande soit considérée comme valide.
  - Type de média : 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 spécifiez 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 spécifier comment la politique de demande de validation de corps est appliquée :
  - Application : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - Permissif : La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - Désactivé : La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Notez que le mode de validation par défaut est Application.
4. Sélectionnez Ajouter des validations.
Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour chaque route.
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 avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Modification d'un fichier JSON pour ajouter des politiques de demande de validation

Pour ajouter des politiques de demande de validation à une spécification de déploiement d'API dans un fichier JSON :

Dans votre éditeur JSON préféré, modifiez la spécification de déploiement d'API existante à laquelle vous souhaitez ajouter des politiques de demande de validation ou créez une spécification de déploiement d'API (voir 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 simple fonction sans serveur Hello World du service des fonctions pour OCI en tant qu'élément dorsal unique :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Ajoutez une section requestPolicies après la section backend pour la route à laquelle appliquer la politique de demande de validation. Par exemple :

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

Pour valider les en-têtes inclus dans une demande à la passerelle d'API pour la route courante, spécifiez une politique 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 dans la demande de validation. Le nom que vous spécifiez n'est pas sensible à la casse. Par exemple X-Username.
- "required": <true|false> indique si l'en-tête spécifié 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 politique de demande de validation d'en-tête, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Par exemple, "validationMode": "PERMISSIVE". Notez que 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 réussissent la validation au service dorsal.
Pour valider les paramètres d'interrogation inclus dans une demande à la passerelle d'API pour la route courante, spécifiez une politique 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 d'interrogation dans la demande de validation. Le nom que vous spécifiez n'est pas sensible à la casse. Par exemple, state.
- "required": <true|false> indique si le paramètre d'interrogation spécifié 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 politique de demande de validation de paramètre d'interrogation, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Par exemple, "validationMode": "PERMISSIVE". Notez que 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 d'interrogation state. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
Pour valider le contenu dans le corps d'une demande à la passerelle d'API pour la route courante, spécifiez une politique 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 la demande doit être l'un des types de contenu que vous spécifiez.
- "content": {"<media-type-1>": {"validationType": "NONE"}, "<media-type-2>": {"validationType": "NONE"}} indique un ou plusieurs 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 politique de demande de validation de corps, comme suit :
  - ENFORCING: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie uniquement les demandes qui réussissent la validation au service dorsal.
  - PERMISSIVE: La passerelle d'API valide toutes les demandes par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal, qu'elles soient validées ou non.
  - DISABLED: La passerelle d'API ne valide aucune demande par rapport à la politique de demande de validation. La passerelle d'API envoie toutes les demandes au service dorsal.
  Par exemple, "validationMode": "PERMISSIVE". Notez que 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 réussissent la validation au service dorsal.
Enregistrez le fichier JSON contenant la spécification de déploiement d'API.
Utilisez comme suit 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 Charger une API existante.
- En spécifiant le fichier JSON dans une demande à l'API REST du service Passerelle d'API.
Pour plus d'informations, voir 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 avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Documentation sur Oracle Cloud Infrastructure

Ajout de la validation de demande aux déploiements d'API

Utilisation de la console pour ajouter des politiques de demande de validation

Modification d'un fichier JSON pour ajouter des politiques de demande de validation