Règle LookupCache

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

Consultez la documentation d'Apigee Edge.

Configure la façon dont les valeurs mises en cache doivent être récupérées lors de l'exécution.

Cette règle est destinée à être utilisée pour une mise en cache à court terme à usage général. Elle est utilisée conjointement avec la règle PopulateCache (pour l'écriture des entrées) et la règle InvalidateCache (pour la validation des entrées).

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Pour la mise en cache des réponses des ressources de backend, consultez la règle ResponseCache .

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

Vous trouverez ci-dessous la liste des éléments que vous pouvez configurer pour cette règle.

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

Un cache partagé est inclus par défaut. Pour utiliser le cache partagé, omettez l'élément <CacheResource> dans la configuration de cette règle.

Pour plus d'informations sur le magasin de données sous-jacent, consultez la page Composants internes du cache. Pour en savoir plus sur la configuration des caches, consultez la page Mise en cache à usage général.

Attributs <LookupCache>

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

Attribut	Description	Par défaut	Presence
`name`	Nom interne de la règle. La valeur de l'attribut `name` peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément `<DisplayName>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
`continueOnError`	Définissez sur `false` pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur `true` pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
`enabled`	Définissez sur `true` pour appliquer la règle. Définissez sur `false` pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	true	Facultatif
`async`	Cet attribut est obsolète.	false	Obsolète

É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>

Par défaut

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut `name` de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Presence Facultatif

Type Chaîne

Élément <AssignTo>

Spécifie la variable dans laquelle l'entrée du cache est attribuée après avoir récupéré le cache. La variable doit être accessible en écriture. Si la recherche dans le cache ne récupère pas de valeur, la variable n'est pas définie.

<AssignTo>variable_to_receive_cached_value</AssignTo>

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	Chaîne

Élément <CacheKey>

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

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

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	N/A

<CacheKey> crée le nom de chaque élément de données stocké dans le cache.

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>12</CacheLookupTimeoutInSeconds>

Valeur par défaut :	12
Présence :	Facultative
Type :	Entier

Élément <CacheResource>

Indique le cache où les messages doivent être stockés.

Omettez cet élément si cette règle (et vos règles PopulateCache et InvalidateCache correspondantes) utilise le cache partagé inclus.

<CacheResource>cache_to_use</CacheResource>

Valeur par défaut :	N/A
Présence :	Facultative
Type :	Chaîne

Pour en savoir plus sur la configuration des caches, consultez la page Mise en cache à usage général.

Élément <CacheKey>/<KeyFragment>

Spécifie une valeur qui doit être incluse dans la clé de cache. Spécifiez une variable à déréférencer avec l'attribut ref, ou une valeur fixe.

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

Valeur par défaut :	N/A
Présence :	Facultative
Type :	N/A

Au moment de l'exécution, Apigee crée la clé de cache en ajoutant la valeur obtenue à partir de l'élément <Scope> ou de l'élément <Prefix> à une concaténation des valeurs résolues de chacun des éléments <KeyFragment>. Pour en savoir plus, consultez la page Utiliser des clés de cache.

Attributs

Attribut	Type	Valeur par défaut	Obligatoire	Description
ref	chaîne		Non	Variable à partir de laquelle obtenir la valeur. Ne doit pas être utilisée si cet élément contient une valeur littérale.

Élément <CacheKey>/<Prefix>

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

<Prefix>prefix_string</Prefix>

Valeur par défaut :	N/A
Présence :	Facultative
Type :	Chaîne

Un élément <Prefix> remplace tout élément <Scope>.

É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>

Valeur par défaut :	"Exclusive"
Présence :	Facultative
Type :	Chaîne

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

Pour en savoir plus, consultez la page Utiliser des clés de cache.

Valeurs acceptables

`Global`	La clé de cache est partagée entre tous les proxys d'API déployés dans l'environnement. La clé de cache prend un préfixe au format orgName __ envName. Si vous définissez une entrée `<CacheKey>` avec l'apiAccessToken `<KeyFragment>` et un champ d'application `<Global>`, chaque entrée est stockée en tant que `orgName__envName__apiAccessToken`, suivie de la valeur sérialisée du jeton d'accès. Pour un proxy d'API déployé dans un environnement appelé "test" dans une organisation appelée "apifactory", les jetons d'accès sont stockés sous la clé de cache suivante : `apifactory__test__apiAccessToken`.
`Application`	Le nom du proxy d'API est utilisé comme préfixe. La clé de cache prend un préfixe au format orgName__envName__applicationName.
`Proxy`	La configuration ProxyEndpoint est utilisée comme préfixe. La clé de cache prend un préfixe au format orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName.
`Target`	La configuration TargetEndpoint est utilisée comme préfixe. La clé de cache prend un préfixe au format orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName.
`Exclusive`	Valeur par défaut. C'est la plus spécifique et présente donc un risque minimal de conflits d'espaces de noms dans un cache donné. Le préfixe prend l'une des deux formes suivantes : Si la règle est associée au flux `ProxyEndpoint`, le préfixe prend la forme ApiProxyName_ProxyEndpointName. Si la règle est associée à `TargetEndpoint`, le préfixe prend le format ApiProxyName_TargetName. La clé de cache prend un préfixe au format orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName. Par exemple, la chaîne complète peut ressembler à ceci : apifactory__test__weatherapi__16__default__apiAccessToken .

Remarques sur l'utilisation

Utilisez cette règle pour la mise en cache à usage général. Lors de l'exécution, la règle LookupCache récupère une valeur du cache en attribuant cette valeur à la variable spécifiée avec l'élément AssignTo (si aucune valeur n'est récupérée, la variable n'est pas définie). La règle recherche la valeur basée sur une clé de cache créée via une configuration qui combine les éléments CacheKey et Scope. En d'autres termes, pour récupérer une valeur particulière ajoutée au cache par une règle PopulateCache, votre règle LookupCache doit définir des éléments liés à la clé de cache de la même manière que la règle PopulateCache.

La mise en cache à usage général avec les règles PopulateCache, LookupCache et InvalidateCache utilise soit un cache que vous configurez, soit un cache partagé inclus par défaut. Dans la plupart des cas, le cache partagé sous-jacent devrait répondre à vos besoins. Pour utiliser le cache par défaut, omettez simplement l'élément <CacheResource>.

Pour en savoir plus sur la configuration des caches, consultez la page Mise en cache à usage général. Pour plus d'informations sur le magasin de données sous-jacent, consultez la page Composants internes du cache.

Variables de flux

Les variables de flux peuvent être utilisées pour configurer le comportement d'exécution dynamique des règles et des flux en fonction des en-têtes HTTP, du contenu des messages ou du contexte disponible dans le flux. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables de flux.

Les variables de flux prédéfinies suivantes sont disponibles après la personnalisation du comportement du cache que vous définissez dans une règle LookupCache.

Variables	Type	Autorisation	Description
lookupcache.{policy-name}.cachename	Chaîne	En lecture seule	Renvoie le nom du cache utilisé dans la règle.
lookupcache.{policy-name}.cachekey	Chaîne	En lecture seule	Renvoie la clé utilisée.
lookupcache.{policy-name}.cachehit	Booléen	En lecture seule	La valeur est "True" si la règle a trouvé une valeur pour la clé de cache spécifiée.
lookupcache.{policy-name}.assignto	Chaîne	En lecture seule	Renvoie la variable à laquelle le cache est attribué.

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

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.

Nom de l'erreur	Cause	Corriger
`InvalidCacheResourceReference`	Cette erreur se produit si l'élément `<CacheResource>` est défini sur un nom qui n'existe pas dans l'environnement dans lequel le proxy d'API est déployé.
`InvalidTimeout`	Si l'élément `<CacheLookupTimeoutInSeconds>` est défini sur un nombre négatif, le déploiement du proxy d'API échoue.
`CacheNotFound`	Cette erreur se produit si le cache spécifique mentionné dans le message d'erreur n'a pas été créé sur un composant du processeur de messages spécifique.