Utiliser des clés de cache

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Lorsque vous utilisez des règles de cache, configurez les clés de cache pour garantir l'unicité des clés de valeur mises en cache. Une clé de cache, ainsi que d'autres valeurs pouvant être configurées, vous offre un moyen fiable de récupérer les mêmes données que celles que vous stockez. Vous utilisez des clés de cache avec les règles PopulateCache, LookupCache, InvalidateCache et ResponseCache.

Apigee utilise les valeurs des éléments de configuration,<Scope>, <CacheKey>/<Prefix> et <CacheKey>/<KeyFragment> pour composer une valeur pour la clé de cache, qui est un identifiant associé à la valeur du cache. La composition des clés de cache fonctionne de la même manière avec toutes les règles de cache.

Avec les éléments de configuration de règle de cache suivants, vous pouvez créer une clé de cache :

Élément de configuration de cache	Description
<Scope> ou <CacheKey> / <Prefix>	Utilisez <Scope> ou les éléments <CacheKey> <Prefix> pour configurer un préfixe à appliquer à la clé de cache finale. <Scope> énumère une liste de valeurs prédéfinies. Les éléments <CacheKey> <Prefix> remplacent <Scope> par une valeur fixe de votre choix.
<CacheKey>/<KeyFragment>	Utilisez un ou plusieurs éléments <CacheKey> <KeyFragment> combinés pour spécifier un identifiant unique pour les entrées de cache. Les valeurs KeyFragment peuvent être des littéraux statiques ou définies à partir de variables.

Apigee compose la clé de cache en deux parties, la partie préfixe et la partie de fragment composite, séparées par un trait de soulignement double.

PREFIX_PART__FRAGMENT_PART

La partie du préfixe est déterminée par l'élément <Scope> ou l'élément <CacheKey> <Prefix> s'il est présent. La partie fragmentée est composée de chacune des valeurs de chaque élément <KeyFragment>, séparées par des traits de soulignement doubles.

Avec la règle ResponseCache, vous pouvez éventuellement ajouter des valeurs de l'en-tête Accept de réponse à cette clé de cache.

Utiliser <CacheKey>

L'élément <CacheKey> configure la création d'un identifiant unique (une clé) par Apigee pour chaque entrée de cache créée. Lorsque Apigee récupère la valeur mise en cache, il utilise la clé de cache pour localiser la valeur correcte. Dans la règle ResponseCache, une configuration définit la clé pour la mise en cache et la récupération. Dans les règles PopulateCache et LookupCache, chaque règle doit posséder des éléments <CacheKey> identiques afin de garantir qu'une valeur extraite du cache correspond à une valeur qui s'y trouve.

L'élément <CacheKey> peut inclure un seul élément <Prefix> facultatif, ainsi qu'un ou plusieurs éléments <KeyFragment>. Au moment de l'exécution, Apigee concatène les valeurs déterminées à partir des deux traits de soulignement pour chaque partie afin de constituer la clé de cache.

Par exemple, la configuration suivante crée une valeur myprefix__hello__world à utiliser dans la clé de cache :

<CacheKey>
    <Prefix>myprefix</Prefix>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

Vous pouvez configurer Apigee pour qu'il utilise une clé de cache composée de manière dynamique en référençant la variable dans un élément <KeyFragment>, comme indiqué ici :

<KeyFragment ref="variable_name"/>

Par exemple, pour que la valeur de la clé de cache contienne le paramètre Content-Type du message de la requête, procédez comme suit :

<KeyFragment ref="request.header.Content-Type"/>

Examinez la configuration suivante :

<CacheKey>
  <Prefix>system1</Prefix>
  <KeyFragment>apiAccessToken</KeyFragment>
  <KeyFragment ref="request.header.Content-Type" />
  <KeyFragment>bar</KeyFragment>
</CacheKey>

Si la variable request.header.Content-Type a pour valeur application/json, la clé de cache est system1__apiAccessToken__application/json__bar.

Vous pouvez utiliser des variables définies par la plate-forme ou personnalisées dans un attribut ref.

Clés de cache dérivées de paramètres de requête

En utilisant des variables telles que request.queryparam.<queryparam_name> et request.querystring, vous pouvez configurer une clé de cache pour que celle-ci intègre des parties de la chaîne de requête d'une requête. Par exemple, l'URL suivante utilise deux paramètres de requête (param1 et param2) que vous pouvez utiliser dans votre clé de cache :

http://myaccount.apigee.net/mydata?param1=value1&param2=value2

Votre élément <CacheKey> peut intégrer ces valeurs avec une configuration telle que :

<CacheKey>
    <KeyFragment ref="request.queryparam.param1" />
    <KeyFragment ref="request.queryparam.param2" />
<CacheKey>

Au moment de l'exécution, la clé de cache inclut les valeurs de paramètres concaténées, comme suit :

prefix_part__value1__value2

Plutôt que de spécifier plusieurs paramètres de requête distincts, une autre solution consiste à utiliser la variable request.querystring, qui insère littéralement la chaîne complète des paramètres comme composant de la clé de cache. Notez que, bien que cette méthode prenne en compte tous les paramètres, si l'ordre des paramètres varie d'une requête à l'autre, la clé sera différente. En d'autres termes, param1=value1&param2=value2 et param2=value2&param1=value1 n'entraînent pas la même valeur de clé de cache.

Utiliser <Scope> et <Préfixe>

Les éléments <Scope> et <CacheKey>/<Prefix> permettent d'organiser les valeurs mises en cache dans un espace de noms. Apigee ajoute à votre clé de cache un préfixe correspondant à la valeur qui en découle. L'avantage d'utiliser un champ d'application ou un préfixe dans votre clé de cache est d'invalider toutes les valeurs qui partagent un même préfixe, avec un seul appel à la règle InvalidateCache.

L'élément <Scope> est utilisé par défaut. Il s'agit d'une énumération dont les valeurs vont de la plus large et à la plus restrictive, cette dernière étant la valeur par défaut. Cette valeur par défaut est utilisée, sauf si vous spécifiez une autre valeur, ou une valeur pour l'élément <Prefix>. Vous pouvez remplacer la valeur <Scope> en utilisant un élément <CacheKey> / <Prefix>, et spécifier ainsi une valeur personnalisée pour l'espace de noms.

Par exemple, la valeur <Scope> "Global", à savoir le champ d'application le plus large, représente le nom de l'organisation et de l'environnement. Ainsi, si votre proxy est déployé dans une organisation appelée "mycompany" et un environnement nommé "prod", la valeur ajoutée en découlant sera la suivante :

mycompany__prod__[FRAGMENT_PART]

Comme décrit dans la règle LookupCache, le champ d'application peut être configuré pour augmenter la spécificité de "Global" à "Exclusive". Le champ d'application "Exclusive" est le plus spécifique, et sous-entend donc un risque minimal de conflits d'espaces de noms dans un cache donné. Chaque entrée de cache possédant le champ d'application "Exclusive" est précédée du préfixe suivant :

orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]

Voici quelques exemples : Nous supposons que la 16e révision de votre proxy nommé "weatherapi" est déployée dans une organisation appelée "mycompany" et un environnement nommé "prod", et que le nom du point de terminaison proxy (proxyEndpoint) est "default", et que la stratégie de cache est associée à un flux dans le proxyEndpoint.

Configuration	Résultat
<Scope>Global</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__hello__world.
<Scope>Exclusive</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__weatherapi__16__default__hello__world
<Scope>Exclusive</Scope> <CacheKey> <Prefix>system1</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	system1__hello__world