Documentation Oracle Cloud Infrastructure

Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API

Découvrez comment contrôler le comportement des déploiements d'API en ajoutant des stratégies de demande et de réponse aux spécifications d'API que vous avez précédemment créées à l'aide d'API Gateway.

Vous pouvez contrôler le comportement d'un déploiement d'API créé sur une passerelle d'API en ajoutant des stratégies de demande et de réponse à la spécification de déploiement d'API :

  • Une stratégie de demande qui décrit les actions à effectuer sur la demande entrante d'un client d'API avant que celle-ci ne soit envoyée à un back-end.
  • Une stratégie de réponse qui décrit les actions à effectuer sur la réponse renvoyée par un back-end avant que celle-ci ne soit envoyée à un client d'API.

Vous pouvez utiliser des stratégies de demande et/ou des stratégies de réponse pour :

  • limiter le nombre de demandes envoyées aux services back-end,
  • activer la prise en charge de la spécification CORS,
  • fournir l'authentification et l'autorisation.
  • ajouter la prise en charge de mTLS
  • valider les demandes avant de les envoyer aux services back-end
  • modifier les demandes entrantes et les réponses sortantes.
  • mettre en cache les réponses pour améliorer les performances et réduire la charge sur les services back-end
  • rendre les déploiements d'API éligibles à l'inclusion dans les plans d'utilisation qui surveillent et gèrent l'accès des abonnés

Vous pouvez ajouter à une spécification de déploiement d'API des stratégies qui s'appliquent de façon globale à tous les routages de la spécification, ainsi que des stratégies qui s'appliquent uniquement à des routages particuliers.

Les stratégies de demande et de réponse API Gateway diffèrent des stratégies IAM, qui contrôlent l'accès aux ressources Oracle Cloud Infrastructure.

Vous pouvez ajouter des stratégies de demande et de réponse à 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 et de réponse

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

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

  2. Dans la section Stratégies de demande d'API de la page Informations de base, indiquez les stratégies de demande qui s'appliquent de façon globale à tous les routages dans la spécification de déploiement d'API :

    • Mutual-TLS : stratégie permettant de contrôler l'accès aux API que vous déployez vers des passerelles d'API en fonction du certificat TLS présenté par le client d'API qui effectue une demande. Vous pouvez uniquement appliquer une stratégie mTLS de manière globale à tous les routages dans la spécification de déploiement d'API (et non à des routages spécifiques). Reportez-vous à Ajout de la prise en charge de mTLS aux déploiements d'API.
    • CORS : stratégie permettant d'activer la prise en charge CORS dans les API que vous déployez vers des passerelles d'API. Vous pouvez également spécifier des stratégies CORS qui s'appliquent à des routages dans la spécification de déploiement d'API (vous n'avez pas besoin d'avoir préalablement spécifié une stratégie CORS globale). Reportez-vous à Ajout de la prise en charge CORS aux déploiements d'API.
    • Limitation de débit : stratégie permettant de limiter le débit d'envoi de demandes aux services back-end à partir des clients d'API. Vous pouvez uniquement appliquer une stratégie de limitation de débit de façon globale à tous les routages dans la spécification de déploiement d'API (et non à des routages spécifiques). Reportez-vous à Limitation du nombre de demandes aux back-ends de passerelle d'API.

  3. Sélectionnez Suivant pour indiquer les options permettant de définir une stratégie de demande d'authentification globale sur la page Authentification.

    La stratégie de demande d'authentification contrôle l'accès aux API que vous déployez vers les passerelles d'API. Une fois que vous avez spécifié une stratégie d'authentification globale, vous pouvez indiquer des stratégies d'autorisation qui s'appliquent à des routages individuels dans la spécification de déploiement d'API. Reportez-vous à Ajout de l'authentification et de l'autorisation aux déploiements d'API.

  4. Sélectionnez Suivant pour saisir les détails de chaque routage dans le déploiement d'API sur la page Routages.

  5. Afin d'indiquer les stratégies de demande qui s'appliquent à un routage spécifique, sélectionnez Afficher les stratégies de demande de routage, ainsi que :

  6. Pour indiquer les stratégies de réponse qui s'appliquent à un routage spécifique, sélectionnez Afficher les stratégies de réponse de routage, puis indiquez les éléments suivants :

  7. Sélectionnez Suivant afin de vérifier les détails saisis pour le déploiement d'API.
  8. Sélectionnez Créer ou Enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
  9. (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 et de réponse

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

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

    Au minimum, la spécification de déploiement d'API doit inclure une section routes contenant les éléments suivants :

    • Un chemin. Par exemple, /hello.
    • Des méthodes. Par exemple, GET.
    • La définition d'un back-end. Par exemple, une URL ou l'OCID d'une fonction dans OCI Functions.

    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": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

  2. Pour ajouter une stratégie de demande qui s'applique de façon globale à tous les routages de la spécification de déploiement d'API, procédez comme suit :

    1. Insérez une section requestPolicies avant la section routes. Par exemple :

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

    2. Incluez une stratégie de demande dans la section requestPolicies.

      Par exemple, pour limiter le nombre de demandes envoyées à tous les routages dans une spécification de déploiement d'API, vous devez inclure la stratégie rateLimiting dans la section requestPolicies comme suit :

      {
  "requestPolicies": {
    "rateLimiting": {
      "rateKey": "CLIENT_IP",
      "rateInRequestsPerSecond": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      Pour plus d'informations sur la stratégie de demande rateLimiting, reportez-vous à Limitation du nombre de demandes aux back-ends de passerelle d'API.

  3. Pour ajouter une stratégie de demande qui s'applique à un seul routage dans la spécification de déploiement d'API, procédez comme suit :

    1. Insérez une section requestPolicies après la section backend du routage. Par exemple :

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

    2. Incluez une stratégie de demande dans la section requestPolicies.

      Par exemple, afin d'activer la prise en charge CORS dans le déploiement d'API pour un routage spécifique, vous devez inclure la stratégie cors dans la section requestPolicies comme suit :

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}

      Pour plus d'informations sur la stratégie de demande cors, reportez-vous à Ajout de la prise en charge CORS aux déploiements d'API.

  4. Pour ajouter une stratégie de réponse qui s'applique à un seul routage dans la spécification de déploiement d'API, procédez comme suit :

    1. Insérez une section responsePolicies après la section backend du routage. Par exemple :

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

    2. Incluez une stratégie de réponse dans la section responsePolicies.

      Par exemple, pour renommer un en-tête X-Username en X-User-ID dans la réponse d'un routage particulier, vous devez inclure la stratégie headerTransformations dans la section responsePolicies comme suit :

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

      Pour plus d'informations sur la stratégie de réponse headerTransformations, reportez-vous à Modification d'un fichier JSON pour ajouter des stratégies de réponse de transformation d'en-tête.

  5. Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.

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