Mise en cache des réponses pour l'amélioration des performances

Afin d'activer et de configurer la mise en cache des réponses pour une passerelle d'API à l'aide de la console, procédez comme suit :

1. Créez ou mettez à jour une passerelle d'API à l'aide de la console.

   Pour plus d'informations, reportez-vous à Création d'une passerelle d'API et à Mise à jour d'une passerelle d'API.

2. Dans la section Options avancées de la boîte de dialogue Créer une passerelle, sélectionnez le bouton Activer en regard de Mise en cache des réponses et procédez comme suit :

   1. Spécifiez les options Serveur de cache, comme suit :
      • Hôte : nom d'hôte du serveur de cache. Par exemple, "cache.example.com".
      • Numéro de port : numéro de port sur le serveur de cache. Par exemple : 6379.
   2. Indiquez les options Informations d'identification du serveur de cache, comme suit :
      • Coffre : nom du coffre dans le service Vault qui contient les informations d'identification permettant de se connecter au serveur de cache.
      • Clé secrète du coffre : nom de la clé secrète dans le coffre indiqué qui contient les informations d'identification permettant de se connecter au serveur de cache.
      • Numéro de version de clé secrète du coffre : version de la clé secrète à utiliser.
   3. Spécifiez les options Connexion au serveur de cache, comme suit :
      • Utiliser SSL/TLS dans les demandes : indique si le serveur de cache est compatible TLS et, par conséquent, si une connexion sécurisée doit être configurée entre la passerelle d'API et le serveur de cache via TLS (anciennement SSL).
      • Vérification du certificat SSL/TLS : indique si la passerelle d'API vérifie le certificat TLS (anciennement SSL) du serveur de cache. Notez que seuls les certificats signés par les autorités de certification publiques sont actuellement vérifiés.
      • Délai d'expiration de connexion : délai d'attente avant l'abandon d'une tentative de connexion au serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas se connecter au serveur de cache dans ce délai, elle n'extrait pas les données précédemment mises en cache à partir du serveur de cache et n'écrit pas de nouvelles données vers le serveur de cache pour une réutilisation future potentielle.
      • Délai d'expiration de la lecture : délai d'attente avant l'abandon d'une tentative de lecture de données à partir du serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas extraire de données du serveur de cache pendant ce temps, elle envoie une demande au service back-end.
      • Délai d'expiration d'envoi : délai d'attente avant l'abandon d'une tentative d'écriture de données sur le serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas envoyer de données au serveur de cache dans ce délai, aucune réponse n'est mise en cache pour une réutilisation future potentielle.
3. Sélectionnez Créer ou Enregistrer les modifications pour créer ou mettre à jour la passerelle d'API.

Afin d'activer et de configurer la mise en cache des réponses pour une passerelle d'API à l'aide de l'interface de ligne de commande et d'un fichier JSON, procédez comme suit :

1. A l'aide de l'éditeur JSON de votre choix, créez un fichier de configuration de cache au format suivant :

   {
     "type" : "EXTERNAL_RESP_CACHE",
     "servers" : [
       {
         "host" : "<cache-server-hostname>",
         "port" : <port-number>
       }
     ],
     "authenticationSecretId" : "<secret-ocid>",
     "authenticationSecretVersionNumber" : <secret-version-number>,
     "isSSLEnabled" : <true|false>,
     "isSSLVerifyDisabled" : <true|false>,
     "connectTimeoutInMs" : <milliseconds>,
     "readTimeoutInMs" : <milliseconds>,
     "readTimeoutInMs" : <milliseconds>
   }

   où :

   • "type" : "EXTERNAL_RESP_CACHE" indique que la mise en cache des réponses doit être activée. Si cette option n'est pas définie, la valeur par défaut est "type" : "NONE", ce qui indique que la mise en cache des réponses est désactivée.
   • "host" : "<cache-server-hostname>" est le nom d'hôte du serveur de cache. Par exemple, "host" : "cache.example.com".
   • "port" : <port-number> est le numéro de port sur le serveur de cache. Par exemple, "port" : 6379.
   • "authenticationSecretId" : "<secret-ocid>" est l'OCID de la clé secrète définie dans un coffre du service Vault qui contient les informations d'identification permettant de se connecter au serveur de cache. Par exemple, "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn"
   • "authenticationSecretVersionNumber" : <secret-version-number> est la version de la clé secrète à utiliser. Par exemple, "authenticationSecretVersionNumber" : 1
   • "isSSLEnabled" : <true|false> indique si le serveur de cache est activé pour TLS, et donc s'il faut configurer une connexion sécurisée entre la passerelle d'API et le serveur de cache sur TLS (anciennement SSL). Si elle n'est pas définie, la valeur par défaut est false.
   • "isSSLVerifyDisabled" : <true|false> indique si la passerelle d'API vérifie le certificat TLS (anciennement SSL) du serveur de cache. Notez que seuls les certificats signés par des autorités de certification publiques sont actuellement vérifiés. Si elle n'est pas définie, la valeur par défaut est false.
   • "connectTimeoutInMs" : <milliseconds> indique le délai d'attente avant l'abandon d'une tentative de connexion au serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas se connecter au serveur de cache pendant cette période, elle n'extrait pas les données précédemment mises en cache du serveur de cache et n'écrit pas de nouvelles données sur le serveur de cache en vue d'une éventuelle réutilisation future. Si elle n'est pas définie, la valeur par défaut est 1000. Par exemple, "connectTimeoutInMs" : 1500
   • "readTimeoutInMs" : <milliseconds> indique le délai d'attente avant l'abandon d'une tentative de lecture de données à partir du serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas extraire les données du serveur de cache pendant cette période, elle envoie une demande au service back-end. Si elle n'est pas définie, la valeur par défaut est 1000. Par exemple, "readTimeoutInMs" : 250
   • "sendTimeoutInMs" : <milliseconds> indique le délai d'attente avant l'abandon d'une tentative d'écriture de données sur le serveur de cache, en millisecondes. Si la passerelle d'API ne peut pas envoyer de données au serveur de cache dans ce délai, les réponses ne sont pas mises en cache en vue d'une éventuelle réutilisation future. Si elle n'est pas définie, la valeur par défaut est 1000. Par exemple, "sendTimeoutInMs" : 1250

   Par exemple :

   {
     "type" : "EXTERNAL_RESP_CACHE",
     "servers" : [
       {
         "host" : "cache.example.com",
         "port" : 6379
       }
     ],
     "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn",
     "authenticationSecretVersionNumber" : 1,
     "isSSLEnabled" : true,
     "isSSLVerifyDisabled" : false,
     "connectTimeoutInMs" : 1000,
     "readTimeoutInMs" : 250,
     "sendTimeoutInMs" : 1000
   }

2. Enregistrez le fichier de configuration du cache sous le nom de votre choix. Par exemple, resp-cache-config.json
3. Utilisez le fichier de configuration de cache lorsque vous créez ou mettez à jour une passerelle d'API à l'aide de l'interface de ligne de commande :
   • Pour créer une passerelle d'API avec mise en cache des réponses activée, suivez les instructions de l'interface de ligne de commande dans Création d'une passerelle d'API et définissez le paramètre --response-cache-details sur le nom et l'emplacement du fichier de configuration de cache. Par exemple :

     oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id ocid1.subnet.oc1.iad.aaaaaaaaz______rca --response-cache-details file:///etc/caches/resp-cache-config.json

   • Pour mettre à jour une passerelle d'API existante afin d'activer la mise en cache des réponses ou de modifier les paramètres de mise en cache des réponses, suivez les instructions de l'interface de ligne de commande dans Mise à jour d'une passerelle d'API et définissez le paramètre --response-cache-details sur le nom et l'emplacement du fichier de configuration de cache. Par exemple :

     oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --response-cache-details file:///etc/caches/resp-cache-config.json

Pour ajouter une demande de mise en cache de réponse et des stratégies 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. Sélectionnez Suivant pour saisir les détails de chaque routage dans le déploiement d'API sur la page Routages, puis sélectionnez Mise en cache des réponses.

3. Sélectionnez l'option Mise en cache pour cette route et indiquez les options de mise en cache des réponses qui s'appliquent à cette route particulière :
   • TTL (Time To Live) pour les réponses mises en mémoire cache en secondes : durée pendant laquelle les données mises en mémoire cache sont disponibles dans le serveur de cache pour ce routage particulier.
   • Ajout de clé de cache : variables de contexte à ajouter à la clé de cache par défaut pour associer plus étroitement une réponse mise en cache à une demande particulière. Par exemple, request.headers[X-Username]. Vous pouvez effectuer une sélection dans une liste de variables de contexte couramment utilisées ou entrer une variable de contexte de votre choix. Ne faites pas précéder la variable de contexte d'un symbole $ ou ne la mettez pas entre accolades (comme vous le feriez si vous ajoutiez la variable de contexte à une URL dans une spécification de déploiement d'API dans un fichier JSON). Pour plus d'informations, reportez-vous à Remarques sur la personnalisation des clés de cache.
4. Pour mettre en cache les réponses des demandes qui contiennent un en-tête d'autorisation, ou qui contiennent un en-tête ou un paramètre de requête identifié dans une stratégie d'authentification, sélectionnez l'option Mettre en cache les réponses avec des en-têtes d'autorisation.

   Notez que la mise en cache des réponses pour de telles demandes peut compromettre la sécurité des données. Pour plus d'informations, reportez-vous à Remarques sur la mise en cache des réponses pour les demandes contenant des informations d'identification (mise en cache privée).

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

Pour ajouter une mise en cache de réponse à un routage particulier, vous devez ajouter une stratégie de demande et une stratégie de réponse.

Pour ajouter la demande de mise en cache des réponses et la stratégie 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 ajouter la mise en cache 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).

   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 spécifier la demande de mise en cache des réponses et la stratégie de réponse qui s'applique à un routage individuel, procédez comme suit :

   1. Insérez à la fois une section requestPolicies et une section responsePolicies après la section back-end du routage auquel appliquer la stratégie. Par exemple :

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

   2. Ajoutez la stratégie de demande responseCacheLookup suivante à la nouvelle section requestPolicies pour l'appliquer au routage :

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "responseCacheLookup": {
                "type": "SIMPLE_LOOKUP_POLICY",
                "isEnabled": true,
                "isPrivateCachingEnabled": <true|false>,
                "cacheKeyAdditions": [<list-of-context-variables>]
              }
            },
            "responsePolicies": {}
          }
        ]
      }

      où :

      • "type": "SIMPLE_LOOKUP_POLICY" est le type de mise en cache des réponses à implémenter. Seule "SIMPLE_LOOKUP_POLICY" est actuellement prise en charge.
      • "isEnabled": true indique que la mise en cache des réponses est activée pour le routage. Pour désactiver temporairement la mise en cache des réponses, définissez "isEnabled": false. Si aucune valeur n'est indiquée, la valeur par défaut est true.
      • "isPrivateCachingEnabled": <true|false> indique si les réponses des demandes contenant un en-tête d'autorisation ou un paramètre d'en-tête ou de requête identifié dans une stratégie d'authentification doivent être mises en mémoire cache. Notez que la mise en cache des réponses pour de telles demandes peut compromettre la sécurité des données. Si elle n'est pas indiquée, la valeur par défaut est false, ce qui indique que les réponses à ces demandes ne sont pas mises en mémoire cache. Pour plus d'informations, reportez-vous à Remarques sur la mise en cache des réponses pour les demandes contenant des informations d'identification (mise en cache privée).
      • "cacheKeyAdditions": [<list-of-context-variables>] est une liste facultative de variables de contexte, séparées par des virgules, à ajouter à la clé de cache par défaut pour associer plus étroitement une réponse mise en cache à une demande particulière. Par exemple, "cacheKeyAdditions": ["request.headers[Accept]"]. Ne faites pas précéder la variable de contexte d'un symbole $ ou placez-la entre accolades (comme vous le feriez si vous ajoutiez la variable de contexte à une URL dans une spécification de déploiement d'API dans un fichier JSON). Pour plus d'informations, reportez-vous à Remarques sur la personnalisation des clés de cache.
   3. Ajoutez la stratégie de réponse responseCacheStorage suivante à la nouvelle section responsePolicies à appliquer au routage :

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "responseCacheLookup": {
                "type": "SIMPLE_LOOKUP_POLICY",
                "isEnabled": true,
                "isPrivateCachingEnabled": false,
                "cacheKeyAdditions": ["request.headers[Accept]"]
              }
            },
            "responsePolicies": {
              "responseCacheStorage": {
                "type": "FIXED_TTL_STORE_POLICY",
                "timeToLiveInSeconds": <seconds>
              }
            }
          }
        ]
      }

      où :

      • "type": "FIXED_TTL_STORE_POLICY" est le type de cache de réponses dans lequel stocker les réponses. Seule "FIXED_TTL_STORE_POLICY" est actuellement prise en charge.
      • "timeToLiveInSeconds": <seconds> indique la durée pendant laquelle les données mises en cache sont disponibles sur le serveur de cache pour ce routage particulier. Par exemple, "timeToLiveInSeconds": 300

   Par exemple :

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "responseCacheLookup": {
             "type": "SIMPLE_LOOKUP_POLICY",
             "isEnabled": true,
             "isPrivateCachingEnabled": false,
             "cacheKeyAdditions": ["request.headers[Accept]"]
           }
         },
         "responsePolicies": {
           "responseCacheStorage": {
             "type":"FIXED_TTL_STORE_POLICY",
             "timeToLiveInSeconds": 300
           }
         }
       }
     ]
   }

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

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

5. (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).