Paramètres de cache pour REST APIs dans API Gateway

Vous pouvez activer la mise en cache des API dans API Gateway pour mettre en cache les réponses de votre point de terminaison. Avec la mise en cache, vous pouvez réduire le nombre d’appels envoyés à votre point de terminaison et également améliorer la latence des demandes adressées à votre API.

Lorsque vous activez la mise en cache pour une étape, API Gateway met en cache les réponses de votre point de terminaison pendant une période spécifiée time-to-live (TTL), en secondes. API Gateway répond ensuite à la demande en recherchant la réponse du point de terminaison dans le cache au lieu d’envoyer une demande à votre point de terminaison. La valeur TTL par défaut pour la mise en cache des API est 300 secondes. La valeur TTL maximale est 3 600 secondes. La valeur TTL = 0 signifie que la mise en cache est désactivée.

Note

La mise en cache est la meilleure solution. Vous pouvez utiliser les CacheMissCount métriques CacheHitCount et d'Amazon CloudWatch pour surveiller les demandes traitées par API Gateway à partir du cache d'API.

La taille maximale d’une réponse qui peut être mise en cache est de 1 048 576 octets. Le chiffrement des données de cache peut augmenter la taille de la réponse lorsqu’elle est mise en cache.

Il s’agit d’un service admissible en vertu de la loi HIPAA. Pour plus d'informations sur AWS le Health Insurance Portability and Accountability Act des États-Unis de 1996 (HIPAA) et sur l'utilisation de AWS services pour traiter, stocker et transmettre des informations de santé protégées (PHI), consultez la section Présentation de la HIPAA.

Important

Lorsque vous activez la mise en cache pour une étape, elle est activée seulement pour les méthodes GET par défaut. Cela permet d’assurer la sécurité et la disponibilité de votre API. Vous pouvez activer la mise en cache pour d’autres méthodes en remplaçant les paramètres de méthode.

Important

La mise en cache est facturée à l’heure en fonction de la taille du cache que vous avez choisie. La mise en cache n'est pas éligible au niveau AWS gratuit. Pour plus d’informations, consultez API Gateway Pricing (Tarification d’API Gateway).

Activation de la mise en cache Amazon API Gateway

Dans API Gateway, vous pouvez activer la mise en cache pour une étape spécifique.

Lorsque vous activez la mise en cache, vous devez choisir une capacité de cache. En général, une plus grande capacité offre de meilleures performances, mais coûte également plus cher. Pour connaître les tailles de cache prises cacheClusterSizeen charge, consultez le guide API Gateway API Reference.

API Gateway active la mise en cache en créant une instance de cache dédiée. Ce processus peut prendre jusqu’à 4 minutes.

API Gateway modifie la capacité de mise en cache en supprimant l’instance de cache existante et en en créant une avec une nouvelle capacité. Toutes les données mises en cache existantes sont supprimées.

Note

La capacité du cache affecte le processeur, la mémoire et la bande passante réseau de l’instance de cache. Par conséquent, la capacité du cache peut affecter les performances de ce dernier.

API Gateway vous recommande d’exécuter un test de charge de 10 minutes pour vérifier que votre capacité de cache est appropriée à votre charge de travail. Assurez-vous que le trafic pendant le test de charge reflète le trafic de production. Par exemple, incluez la montée en puissance, le trafic constant et les pics de trafic. Le test de charge doit inclure des réponses pouvant être fournies à partir du cache, ainsi que des réponses uniques qui ajoutent des éléments au cache. Surveillez les mesures de latence, 4xx, 5xx, d’accès au cache et d’échec d’accès au cache pendant le test de charge. Ajustez votre capacité de cache selon vos besoins en fonction de ces mesures. Pour obtenir plus d’informations sur les tests de charge, consultez l’article How do I select the best API Gateway cache capacity to avoid hitting a rate limit? (Comment sélectionner la meilleure capacité de cache d’API Gateway pour éviter de se heurter à une limite de débit ?).

AWS Management Console

Dans la console API Gateway, la mise en cache est configurée à la page Étapes. Vous allez configurer le cache de l’étape et spécifier un paramètre de cache au niveau de la méthode par défaut. Si vous activez le cache au niveau de la méthode par défaut, la mise en cache au niveau de la méthode est activée pour toutes les méthodes GET de votre étape, à moins que cette méthode comporte un remplacement de méthode. Toutes les méthodes GET supplémentaires que vous déployez pour votre étape disposeront d’un cache au niveau de la méthode. Pour configurer le paramètre de mise en cache au niveau de la méthode pour des méthodes spécifiques de votre étape, vous pouvez utiliser des remplacements de méthode. Pour plus d’informations sur les remplacements de méthode, consultez Remplacement de la mise en cache au niveau de l’étape API Gateway par la mise en cache au niveau de la méthode.

Pour configurer la mise en cache des API pour une étape donnée :

1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

2. Choisissez Stages (Étapes).

3. Dans la liste Stages (Étapes) de l’API, choisissez l’étape.

4. Dans la section Détails de l’étape, choisissez Modifier.

5. Sous Paramètres supplémentaires, pour Paramètres de cache, activez Configurer le cache d’API.

   Cette opération configure un cluster de cache pour votre étape.

6. Pour activer la mise en cache pour votre étape, activez Mise en cache au niveau de la méthode par défaut.

   La mise en cache au niveau de la méthode est alors activée pour toutes les méthodes GET de votre étape. Toutes les méthodes GET supplémentaires que vous déployez pour cette étape disposeront d’un cache au niveau de la méthode.

   Note

   S’il existe déjà un paramètre de cache au niveau de la méthode, celui-ci ne sera pas affecté par la modification du paramètre de cache au niveau de la méthode par défaut.

   

7. Sélectionnez Enregistrer les modifications.

AWS CLI

La commande update-stage suivante met à jour un stage pour provisionner un cache et active la mise en cache au niveau de la méthode pour toutes les GET méthodes de votre stage :

aws apigateway update-stage \
    --rest-api-id a1b2c3 \
    --stage-name 'prod' \
    --patch-operations file://patch.json

Le contenu de patch.json est le suivant :

[
     {
          "op": "replace",
          "path": "/cacheClusterEnabled",
          "value": "true"
     },
     {
          "op": "replace",
          "path": "/cacheClusterSize",
          "value": "0.5"
     },
     {
        "op": "replace",
        "path": "/*/*/caching/enabled",
        "value": "true"
     }
]

Note

S’il existe déjà un paramètre de cache au niveau de la méthode, celui-ci ne sera pas affecté par la modification du paramètre de cache au niveau de la méthode par défaut.

Note

Le processus de création ou de suppression d’un cache prend environ 4 minutes dans API Gateway.

Lorsqu’un cache est créé, la valeur du champ Cluster de cache passe de Create in progress à Active. Lorsqu’un cache est supprimé, la valeur du champ Cluster de cache passe de Delete in progress à Inactive.

Lorsque vous activez la mise en cache au niveau de la méthode pour toutes les méthodes de votre étape, la valeur Mise en cache au niveau de la méthode par défaut devient Active. Si vous désactivez la mise en cache au niveau de la méthode pour toutes les méthodes de votre étape, la valeur Mise en cache au niveau de la méthode par défaut devient Inactive. S’il existe déjà un paramètre de cache au niveau de la méthode, il ne sera pas affecté par la modification du statut du cache.

Lorsque vous activez la mise en cache dans la section Paramètres de cache d’une étape, seules les méthodes GET sont mises en cache. Pour assurer la sécurité et la disponibilité de votre API, nous vous recommandons de ne pas modifier ce paramètre. Vous pouvez cependant activer la mise en cache pour d’autres méthodes en remplaçant les paramètres de méthode.

Si vous souhaitez vérifier si la mise en cache fonctionne comme prévu, vous avez deux options générales :

• Inspectez les CloudWatch métriques de CacheHitCountet CacheMissCountpour votre API et votre stage.

• Placez un horodatage dans la réponse.

Note

N'utilisez pas l'X-Cacheen-tête de la CloudFront réponse pour déterminer si votre API est servie à partir de votre instance de cache d'API Gateway.

Remplacement de la mise en cache au niveau de l’étape API Gateway par la mise en cache au niveau de la méthode

Vous pouvez remplacer les paramètres de cache au niveau de l’étape en activant ou en désactivant la mise en cache d’une méthode spécifique. Vous pouvez également modifier la période TTL, ou activer ou désactiver le chiffrement des réponses mises en cache.

Si vous pensez qu'une méthode que vous mettez en cache recevra des données sensibles dans ses réponses, chiffrez les données de votre cache. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d'informations, consultez la section Contrôles Amazon API Gateway dans le guide de AWS Security Hub l'utilisateur.

AWS Management Console

Si vous modifiez le paramètre de mise en cache au niveau de la méthode par défaut dans Détails de l’étape, les paramètres de cache au niveau de la méthode ayant des remplacements n’en seront pas affectés.

Si vous prévoyez qu’une méthode que vous mettez en cache va recevoir des données sensibles dans ses réponses, dans Cache Settings (Paramètres de cache), sélectionnez Encrypt cache data (Chiffrer les données de cache).

Pour configurer la mise en cache des API pour les méthodes individuelles à l’aide de la console :

1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

2. Choisissez l’API.

3. Choisissez Stages (Étapes).

4. Dans la liste Stages (Étapes) de l’API, développez l’étape et choisissez une méthode dans l’API.

5. Dans la section Dérogations de méthode, choisissez Modifier.

6. Dans la section Paramètres de méthode, activez ou désactivez Activer le cache de la méthode ou personnalisez les autres options souhaitées.

   Note

   La mise en cache n’est pas active tant que vous n’avez pas configuré un cluster de cache pour votre étape.

7. Choisissez Save (Enregistrer).

AWS CLI

La commande update-stage suivante désactive le cache uniquement pour la GET /pets méthode :

aws apigateway update-stage /
    --rest-api-id a1b2c3 /
    --stage-name 'prod' /
    --patch-operations file://patch.json

Le contenu de patch.json est le suivant :

[{
        "op": "replace",
        "path": "/~1pets/GET/caching/enabled",
        "value": "false"
}]

Utilisation de paramètres de méthode ou d’intégration en tant que clés de cache pour indexer les réponses mises en cache

Vous pouvez utiliser un paramètre de méthode ou d’intégration en tant que clés de cache pour indexer les réponses mises en cache. Cela inclut les en-têtes personnalisés, les chemins d’URL ou les chaînes de requête. Vous pouvez spécifier tout ou partie de ces paramètres comme clé de cache, mais vous devez spécifier au moins une valeur. Si vous disposez d’une clé de cache, API Gateway met en cache les réponses de chaque valeur de clé séparément, y compris en l’absence de la clé de cache.

Note

Les clés de cache sont obligatoires lorsque vous configurez la mise en cache d’une ressource.

Par exemple, supposons que vous avez une demande au format suivant :

GET /users?type=... HTTP/1.1
host: example.com
...
        

Dans cette demande, type peut prendre la valeur admin ou regular. Si vous incluez le paramètre type dans la clé de cache, les réponses de GET /users?type=admin sont mises en cache séparément de celles de GET /users?type=regular.

Lorsqu’une demande de méthode ou d’intégration utilise plus d’un paramètre, vous pouvez choisir d’inclure certains ou la totalité des paramètres pour créer la clé de cache. Par exemple, vous pouvez inclure uniquement le paramètre type dans la clé de cache pour la demande suivante, effectuée dans l’ordre indiqué pendant une période TTL :

GET /users?type=admin&department=A HTTP/1.1
host: example.com
...
        

La réponse de cette demande est mise en cache et elle est utilisée pour servir la demande suivante :

GET /users?type=admin&department=B HTTP/1.1
host: example.com
...
        

AWS Management Console

Pour inclure un paramètre de demande de méthode ou d’intégration dans une clé de cache dans la console API Gateway, sélectionnez Caching (Mise en cache) après avoir ajouté le paramètre.

AWS CLI

La commande put-method suivante crée une GET méthode et nécessite le paramètre de chaîne de type requête :

aws apigateway put-method /
    --rest-api-id a1b2c3 /
    --resource-id aaa111 /
    --http-method GET /
    --authorization-type "NONE" /
    --request-parameters "method.request.querystring.type=true"

La commande put-integration suivante crée une intégration pour la GET méthode avec un point de terminaison HTTP et indique qu'API Gateway met en cache le paramètre de demande de type méthode :

aws apigateway put-integration /
    --rest-api-id a1b2c3 /
    --resource-id aaa111 /
    --http-method GET /
    --type HTTP /
    --integration-http-method GET /
    --uri 'https://example.com' /
    --cache-key-parameters "method.request.querystring.type"

Pour spécifier un paramètre de demande d'intégration dans le cache d'API Gateway, integration.request.location.name utilisez-le comme paramètre de clé de cache.

Vidage du cache d’étape d’API dans API Gateway

Lorsque la mise en cache des API est activée, vous pouvez vider le cache au niveau d’une étape d’API afin de garantir que les clients de l’API obtiennent les réponses les plus récentes de vos points de terminaison d’intégration.

AWS Management Console

Pour vider le cache du stage de l'API

1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

2. Choisissez une API dotée d'un stage avec un cache.

3. Dans le volet de navigation principal, choisissez Stages, puis choisissez votre étape avec un cache.

4. Choisissez le menu Actions de la scène, puis sélectionnez Vider le cache de la scène.

AWS CLI

La flush-stage-cachecommande suivante vide le cache de la scène :

aws apigateway flush-stage-cache \
    --rest-api-id a1b2c3 \
    --stage-name prod

Note

Une fois que le cache est vidé, les réponses sont traitées à partir du point de terminaison d’intégration jusqu’à ce que le cache soit recréé. Durant cette période, le nombre de demandes envoyées au point de terminaison d’intégration peut augmenter. Cela peut temporairement augmenter la latence globale de votre API.

Invalidation d’une entrée de cache API Gateway

Un client de votre API peut invalider une entrée de cache existante et la recharger à partir du point de terminaison d’intégration pour les différentes demandes. Le client doit envoyer une demande contenant l’en-tête Cache-Control: max-age=0. Le client reçoit la réponse directement du point de terminaison d’intégration et non du cache, sous réserve qu’il dispose de l’autorisation nécessaire. L’entrée de cache existante est alors remplacée par la nouvelle réponse, qui est extraite du point de terminaison d’intégration.

Pour accorder cette autorisation à un client, attachez une politique au format suivant à un rôle d’exécution IAM pour l’utilisateur.

Note

L’invalidation du cache entre comptes n’est pas prise en charge.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:InvalidateCache"
      ],
      "Resource": [
        "arn:aws:execute-api:region:account-id:api-id/stage-name/GET/resource-path-specifier"
      ]
    }
  ]
}            
        

Cette politique autorise le service d’exécution API Gateway à invalider le cache pour les demandes sur les ressources spécifiées. Pour spécifier un groupe de ressources ciblées, utilisez un caractère générique (*) pour account-id, api-id et les autres entrées de la valeur d’ARN de Resource. Pour plus d’informations sur la définition d’autorisations pour le service d’exécution API Gateway, consultez Contrôle de l’accès à une API REST avec des autorisations IAM.

Si vous n’imposez aucune politique InvalidateCache (ou si vous activez la case à cocher Require authorization (Exiger une autorisation) dans la console), n’importe quel client peut invalider le cache API. Si tous les clients ou la plupart d’entre eux invalident le cache API, cela peut augmenter la latence de votre API de façon significative.

Lorsque la politique est en place, la mise en cache est activée et l’autorisation est requise.

Vous pouvez spécifier la manière dont API Gateway gère les demandes non autorisées en choisissant l'une des options suivantes :

Echouer la demande avec le code d'état 403

API Gateway renvoie une 403 Unauthorized réponse.

Pour définir cette option à l'aide de l'API, utilisez FAIL_WITH_403.

Ignorer l'en-tête de contrôle du cache ; ajouter un avertissement dans l'en-tête de réponse

API Gateway traite la demande et ajoute un en-tête d'avertissement dans la réponse.

Pour définir cette option à l'aide de l'API, utilisez SUCCEED_WITH_RESPONSE_HEADER.

Ignorer l'en-tête de contrôle du cache

API Gateway traite la demande et n'ajoute pas d'en-tête d'avertissement dans la réponse.

Pour définir cette option à l'aide de l'API, utilisez SUCCEED_WITHOUT_RESPONSE_HEADER.

Vous pouvez définir le comportement de gestion des demandes non autorisées à l'aide de la console API Gateway ou AWS CLI.

AWS Management Console

Pour spécifier le mode de traitement des demandes non autorisées

1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

2. Choisissez une API dotée d'un stage avec un cache.

3. Dans le volet de navigation principal, choisissez Stages, puis choisissez votre étape avec un cache.

4. Pour les détails de l'étape, choisissez Modifier.

5. Pour le traitement des demandes non autorisées, sélectionnez une option.

6. Choisissez Continuer.

7. Passez en revue vos modifications et choisissez Enregistrer les modifications.

AWS CLI

La commande update-stage suivante met à jour une étape pour gérer les demandes non autorisées en rejetant la demande avec le code d'état 403 :

aws apigateway update-stage /
    --rest-api-id a1b2c3 /
    --stage-name 'prod' /
    --patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"'

AWS CloudFormation exemple d'une étape avec un cache

Le AWS CloudFormation modèle suivant crée un exemple d'API, fournit un cache de 0.5 Go pour la Prod phase et active la mise en cache au niveau de la méthode pour toutes les méthodes. GET

Important

La mise en cache est facturée à l’heure en fonction de la taille du cache que vous avez choisie. La mise en cache n’est pas éligible pour l’offre gratuite AWS . Pour plus d’informations, consultez API Gateway Pricing (Tarification d’API Gateway).

Exemple de AWS CloudFormation modèle

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Name: cache-example
  PetsResource:
    Type: 'AWS::ApiGateway::Resource'
    Properties:
      RestApiId: !Ref Api
      ParentId: !GetAtt Api.RootResourceId
      PathPart: 'pets'
  PetsMethodGet:
    Type: 'AWS::ApiGateway::Method'
    Properties:
      RestApiId: !Ref Api
      ResourceId: !Ref PetsResource
      HttpMethod: GET
      ApiKeyRequired: true
      AuthorizationType: NONE
      Integration:
        Type: HTTP_PROXY
        IntegrationHttpMethod: GET
        Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
  ApiDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn:
      - PetsMethodGet
    Properties:
      RestApiId: !Ref Api
  ApiStage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
      StageName: Prod
      Description: Prod Stage with a cache
      RestApiId: !Ref Api
      DeploymentId: !Ref ApiDeployment
      CacheClusterEnabled: True
      CacheClusterSize: 0.5
      MethodSettings:
        - ResourcePath: /*
          HttpMethod: '*'
          CachingEnabled: True

Exemple de AWS CloudFormation modèle

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Name: cache-example
  PetsResource:
    Type: 'AWS::ApiGateway::Resource'
    Properties:
      RestApiId: !Ref Api
      ParentId: !GetAtt Api.RootResourceId
      PathPart: 'pets'
  PetsMethodGet:
    Type: 'AWS::ApiGateway::Method'
    Properties:
      RestApiId: !Ref Api
      ResourceId: !Ref PetsResource
      HttpMethod: GET
      ApiKeyRequired: true
      AuthorizationType: NONE
      Integration:
        Type: HTTP_PROXY
        IntegrationHttpMethod: GET
        Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
  ApiDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn:
      - PetsMethodGet
    Properties:
      RestApiId: !Ref Api
  ApiStage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
      StageName: Prod
      Description: Prod Stage with a cache
      RestApiId: !Ref Api
      DeploymentId: !Ref ApiDeployment
      CacheClusterEnabled: True
      CacheClusterSize: 0.5
      MethodSettings:
        - ResourcePath: /*
          HttpMethod: '*'
          CachingEnabled: True