Règle ResponseCache

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

La règle ResponseCache met en cache les données d'une ressource backend, ce qui réduit le nombre de requêtes adressées à la ressource. Lorsque des applications envoient des requêtes au même URI, vous pouvez utiliser cette règle pour renvoyer des réponses mises en cache au lieu de transférer ces requêtes au serveur backend. La règle ResponseCache peut améliorer les performances de votre API en réduisant la latence et le trafic réseau.

Vous trouverez probablement la règle ResponseCache très utile lorsque les données backend utilisées par votre API ne sont mises à jour que périodiquement. Imaginons, par exemple, que vous disposiez d'une API qui expose les données du rapport météorologique actualisées toutes les 10 minutes. En utilisant la règle ResponseCache pour renvoyer des réponses mises en cache entre les actualisations, vous pouvez réduire le nombre de requêtes atteignant le backend. Cela réduit également le nombre de sauts de réseau.

Pour une mise en cache à court terme, pensez à utiliser la règle de remplissage de cache. Cette règle est utilisée avec la règle de consultation de cache (pour la lecture des entrées de cache) et la règle d'invalidation de cache (pour l'invalidation des entrées).

Exemples

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

Attributs <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <CacheKey>

Configure un pointeur unique vers un élément de données stocké dans le cache.

Les clés de cache sont limitées à une taille de 2 Ko.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

<CacheKey> crée le nom de chaque élément de données stocké dans le cache. La clé est souvent définie à l'aide d'une valeur provenant d'en-têtes d'entités ou de paramètres de requête. Dans ce cas, l'attribut "ref" de l'élément spécifie une variable contenant la valeur de la clé.

Au moment de l'exécution, les valeurs <KeyFragment> sont précédées de la valeur de l'élément <Scope> ou de la valeur <Prefix>. Par exemple, les résultats suivants génèrent une clé de cache UserToken__apiAccessToken__<value_of_client_id> :

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

Vous utilisez conjointement l'élément <CacheKey> avec <Prefix> et <Scope>. Pour en savoir plus, consultez la page Utiliser des clés de cache.

Élément <CacheLookupTimeoutInSeconds>

Indique le nombre de secondes après lequel une recherche dans le cache ayant échoué est considérée comme un défaut de cache. Si cela se produit, le flux reprend le long du chemin de défaut de cache.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Élément <CacheResource>

Indique le cache où les messages doivent être stockés. Omettez cet élément pour utiliser le cache partagé inclus. Vous devez spécifier un élément CacheResource par nom si vous souhaitez pouvoir effacer de manière administrative les entrées contenues dans le cache. Pour en savoir plus, consultez la section Caches.

<CacheResource>cache_to_use</CacheResource>

Pour en savoir plus sur la configuration des caches, consultez la page Créer et modifier un cache d'environnement.

Élément <CacheKey>/<KeyFragment>

Spécifie une valeur à inclure dans la clé de cache, créant ainsi un espace de noms pour les requêtes correspondantes aux réponses mises en cache.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Il peut s'agir d'une clé (un nom statique que vous fournissez) ou d'une valeur (un ensemble d'entrées dynamique faisant référence à une variable). Tous les fragments spécifiés combinés (plus le préfixe) sont concaténés pour créer la clé de cache.

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

Vous utilisez conjointement l'élément <KeyFragment> avec <Prefix> et <Scope>. Pour en savoir plus, consultez la page Utiliser des clés de cache.

Attributs

Élément <CacheKey>/<Prefix>

Spécifie une valeur à utiliser comme préfixe de clé de cache.

<Prefix>prefix_string</Prefix>

Utilisez cette valeur à la place de <Scope> lorsque vous souhaitez spécifier votre propre valeur plutôt qu'une valeur énumérée <Scope>. Si cette valeur est définie, <Prefix> ajoute la valeur de la clé de cache pour les entrées écrites dans le cache. La valeur de l'élément <Prefix> remplace celle de l'élément <Scope>.

Vous utilisez conjointement l'élément <Prefix> avec <CacheKey> et <Scope>. Pour en savoir plus, consultez la page Utiliser des clés de cache.

Élément <ExcludeErrorResponse>

Actuellement, cette règle met en cache par défaut les réponses HTTP contenant tout code d'état possible. Cela signifie que les réponses de réussite et d'erreur sont mises en cache. Par exemple, les réponses avec les codes d'état 2xx et 3xx sont mises en cache par défaut.

Définissez cet élément sur true si vous ne souhaitez pas mettre en cache les réponses cibles avec des codes d'état d'erreur HTTP. Seules les réponses comportant des codes d'état de 200 à 205 seront mises en cache si cet élément a la valeur true. Ce sont les seuls codes d'état HTTP que Edge compte comme "succès" et vous ne pouvez pas modifier cette association.

Pour en savoir plus sur les formats d'un cache de réponse dans lesquels cet élément est utile, consultez ce post destiné à la communauté.

Remarque : Dans une prochaine version (à déterminer), le paramètre par défaut de cet élément sera remplacé par "true". Consultez les Notes de version d'Apigee pour plus de détails.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Élément <ExpirySettings>

Indique la date d'expiration d'une entrée de cache. Lorsqu'il est présent, l'élément <TimeoutInSeconds> remplace à la fois <TimeOfDay> et <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Élément <ExpirySettings>/<ExpiryDate>

Spécifie la date d'expiration d'une entrée de cache. Utilisez le formulaire mm-dd-yyyy. Lorsqu'il est présent, le frère de cet élément, <TimeoutInSeconds>, remplace <ExpiryDate>.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Attributs

<ExpiryDate ref="" />

Élément <ExpirySettings>/<TimeOfDay>

Heure de la journée à laquelle une entrée de cache doit expirer. Utilisez le formulaire hh:mm:ss. Lorsqu'il est présent, le frère de cet élément, <TimeoutInSeconds>, remplace <TimeOfDay>.

Saisissez l'heure de la journée au format HH:mm:ss, où HH représente l'heure au format 24 heures. Par exemple, 14:30:00 pour 2:30 dans l'après-midi.

Pour l'heure de la journée, les paramètres régionaux et le fuseau horaire par défaut varient en fonction de l'emplacement où est exécuté le code (non connu lors de la configuration de la règle). Pour en savoir plus sur la configuration paramètres régionaux, consultez la section Créer et modifier un le cache de l'environnement.

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Attributs

Élément <ExpirySettings>/<TimeoutInSec>

Durée en secondes après laquelle une entrée de cache doit expirer.

Élément <ExpirySettings>/<TimeoutInSeconds>

Durée en secondes après laquelle une entrée de cache doit expirer. Lorsqu'il est présent, cet élément remplace ses frères, <TimeOfDay> et <ExpiryDate>.

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

Remarque : Indiquez une valeur de délai d'expiration par défaut à utiliser si la valeur "ref" ne reçoit pas de valeur de la variable duration_variable.

Attributs

Élément <Scope>

Énumération permettant de créer un préfixe pour une clé de cache lorsqu'un élément <Prefix> n'est pas fourni dans l'élément <CacheKey>.

<Scope>scope_enumeration</Scope>

Le paramètre <Scope> détermine une clé de cache précédée selon la valeur <Scope>. Par exemple, une clé de cache se présente sous la forme suivante lorsque le champ d'application est défini sur Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

Si un élément <Prefix> figure dans <CacheKey>, il remplace la valeur de l'élément <Scope>. Les valeurs valides incluent les énumérations ci-dessous.

Vous utilisez conjointement l'élément <Scope> avec <CacheKey> et <Prefix>. Pour en savoir plus, consultez la page Utiliser des clés de cache.

Valeurs acceptables

apifactory__test__weatherapi__16__default__apiAccessToken

Élément <SkipCacheLookup>

Définit une expression qui, si elle est définie sur true au moment de l'exécution, spécifie que la recherche dans le cache doit être ignorée et le cache actualisé. Consultez également cette vidéo sur l'utilisation de la règle SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

À partir de l'exemple suivant, si la variable de contournement est définie sur true dans un en-tête entrant, la recherche dans le cache est ignorée et le cache est actualisé.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

Élément <SkipCachePopulation>

Définit une expression qui, si elle est définie sur true au moment de l'exécution, spécifie qu'une écriture dans le cache doit être ignorée. Consultez également cette vidéo sur l'utilisation de la règle SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Par exemple, ce qui suit ignore l'écriture dans le cache si le code d'état de la réponse est supérieur ou égal à 400 :

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

Élément <UseAcceptHeader>

Définissez cet élément sur true pour ajouter à la clé de cache d'une entrée de cache de réponse des valeurs issues des en-têtes Accept de la réponse.

Edge utilise les éléments Accept, Accept-Encoding et Accept-Language et Accept-Charset lors du calcul de la clé de cache. Cette approche empêche un client d'obtenir un type de contenu qu'il n'a pas demandé.

Par exemple, déterminez si deux requêtes proviennent de la même URL, où la première requête accepte gzip, mais pas la seconde. La première requête est mise en cache et l'entrée mise en cache est (probablement) une réponse compressée avec gzip. La seconde requête lit la valeur mise en cache et peut renvoyer une entrée compressée avec gzip à un client qui ne parvient pas à lire le format gzip.

Pour en savoir plus, consultez la section Configurer une clé de cache.

<UseAcceptHeader>false</UseAcceptHeader>

Élément <UseResponseCacheHeaders>

Définissez cet élément sur true pour que les en-têtes de réponse HTTP soient pris en compte lors de la définition de la valeur TTL (Time To Live) de la réponse dans le cache. Lorsque c'est vrai, Edge considère les valeurs du les en-têtes de réponse suivants, en comparant les valeurs avec celles définies par <ExpirySettings> lorsque vous définissez la valeur TTL (Time To Live) :

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

Pour en savoir plus, consultez la section Définir le délai d'expiration des entrées de cache.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Remarques sur l'utilisation

La taille maximale de chaque objet mis en cache est de 256 ko. (Pour obtenir des informations détaillées sur la cache de processus, consultez la section Cache interne.)

Via la configuration de la stratégie ResponseCache, vous pouvez faire en sorte que Edge inclue la réponse HTTP en-têtes pour définir l'expiration des entrées de cache et les clés de cache. Cette section explique comment utiliser la règle avec des en-têtes pour gérer le délai d'expiration du cache et les clés de cache.

Pour en savoir plus sur la manière dont Edge gère les en-têtes de réponse avec la stratégie ResponseCache, consultez la section Compatibilité avec les en-têtes de réponse HTTP.

Définir le délai d'expiration des entrées de cache

Comme pour la règle de remplissage du cache, vous pouvez définir l'expiration d'une entrée de cache de réponse (c'est-à-dire sa durée de vie) à l'aide de l'élément <ExpirySettings>. Dans la stratégie ResponseCache, vous pouvez aussi avoir tenir compte des en-têtes de réponse lorsqu'ils sont présents.

Pour utiliser les en-têtes de réponse, définissez la valeur de l'élément <UseResponseCacheHeaders> sur true. Ce paramètre oblige Edge à prendre en compte les en-têtes de réponse et à les comparer à la valeur définie par <ExpirySettings>, puis utilisez la valeur la plus faible entre les deux. Quand ? compte tenu des en-têtes de réponse, Edge choisit la valeur disponible comme décrit dans le suivantes:

Par exemple, imaginons qu'une réponse soit mise en cache avec les valeurs suivantes :

• Aucune valeur Cache-Control s-maxage
• Une valeur de Cache-Control max-age
• Une date Expires dans trois jours
• Une valeur <ExpirySettings> TimeoutInSeconds de 600

Dans ce cas, la valeur Cache-Control max-age serait utilisée pour la valeur TTL, car elle est inférieure à la valeur <ExpirySettings> et parce qu'il n'y a pas de valeur Cache-Control s-maxage (qui l'emporte sur max-age).

Configurer une clé de cache

Comme pour les règles de cache à usage général, telles que la règle de remplissage de cache, avec la règle ResponseCache, vous utilisez les éléments <CacheKey> et <Scope> afin de configurer la création de clés de cache pour les entrées de cache. Avec la règle ResponseCache, vous pouvez également rendre les clés de cache plus significatives en ajoutant des en-têtes Accept de réponse aux valeurs de clé.

Pour obtenir des informations générales sur la configuration des clés de cache, consultez la section Utiliser des clés de cache. Pour en savoir plus sur l'utilisation des en-têtes "Accept", consultez la page <UseAcceptHeader>.

À propos du chiffrement du cache

Edge pour le cloud public:le cache est chiffré uniquement dans PCI : et compatible avec la loi HIPAA pour les entreprises. Le chiffrement de ces organisations est configuré lors de la gestion de leurs comptes.

Variables de flux

Les variables de flux prédéfinies suivantes sont renseignées lorsqu'une règle ResponseCache est exécutée. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables.

Codes d'erreur

Cette section décrit les messages d'erreur et les variables de flux définies lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance pour un proxy. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Préfixe de code d'erreur

N/A

Erreurs d'exécution

Cette règle ne génère aucune erreur d'exécution.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

ND

Exemple de réponse d'erreur

N/A

Schéma

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.