Règle PopulateCache

Règle extensible

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

Consultez la documentation d' Apigee Edge.

La règle PopulateCache configure la façon dont les valeurs mises en cache doivent être écrites lors de l'exécution.

La stratégie d'insertion du cache est conçue pour écrire des entrées dans un cache à usage général à court terme. Elle est utilisée conjointement avec la règle de recherche du cache (pour lire les entrées de cache) et la règle d'invalidation du cache (pour invalider les 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 de réponse du cache.

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.

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

Attributs <PopulateCache>

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 :

 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

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

Valeur par défaut :

N/A

Présence :

 Requis

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

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

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

<CacheResource>cache_to_use</CacheResource>

Valeur par défaut :

N/A

Présence :

 Facultatif

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 :

 zéro ou plus

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 fixe à utiliser comme préfixe de clé de cache.

<Prefix>prefix_string</Prefix>

Valeur par défaut :

N/A

Présence :

 Facultatif

Type :

Chaîne

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

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.

Élément <ExpirySettings>

Indique la date d'expiration d'une entrée de cache.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Valeur par défaut :

N/A

Présence :

 Requis

Type :

N/A

Éléments enfants de <ExpirySettings>

Utilisez exactement un élément enfant. Le tableau suivant fournit une description des éléments enfants de <ExpirySettings> :

Élément enfant Description
<TimeoutInSeconds>

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

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

Cet élément remplace l'élément TimeoutInSec, désormais obsolète.
<ExpiryDate>

Spécifie la date d'expiration d'une entrée de cache. Spécifiez une chaîne au format mm-dd-yyyy.

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

Si la date spécifiée est antérieure à la date actuelle, la règle applique la valeur TTL maximale à l'entrée mise en cache. Cette valeur TTL maximale est de 30 jours.
<TimeOfDay>

Spécifie l'heure à laquelle une entrée de cache doit expirer. Spécifiez une chaîne au format HH:mm:ss, où HH représente l'heure au format 24 heures, dans le fuseau horaire UTC. Par exemple, 14:30:00 signifie 2:30 dans l'après-midi.

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

Vous ne devez spécifier qu'un seul des éléments enfants possibles. Si vous spécifiez plusieurs éléments, l'ordre de priorité est le suivant : TimeoutInSeconds, ExpiryDate, TimeOfDay.

Avec chacun des éléments enfants de <ExpirySettings> ci-dessus, si vous spécifiez l'attribut facultatif ref sur l'élément enfant, la règle récupère la valeur d'expiration à partir de la variable de contexte nommée. Si la variable n'est pas définie, la règle utilise la valeur de texte littéral de l'élément enfant.

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

 Facultatif

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 prend le format suivant lorsque le champ d'application est défini sur Exclusive :

orgName__envName__apiProxyName__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

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__apiProxyName.
Proxy

La configuration ProxyEndpoint est utilisée comme préfixe.

La clé de cache prend un préfixe au format orgName__envName__apiProxyName__proxyEndpointName .
Target

La configuration TargetEndpoint est utilisée comme préfixe.

La clé de cache prend un préfixe au format orgName__envName__apiProxyName__targetEndpointName .
Exclusive

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

Par exemple, la chaîne complète peut ressembler à ceci :

apifactory__test__weatherapi__default__apiAccessToken
.

Élément <Source>

Spécifie la variable dont la valeur doit être écrite dans le cache.

<Source>source_variable</Source>

Valeur par défaut :

N/A

Présence :

 Requis

Type :

Chaîne

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 <PopulateCache> écrit les données de la variable que vous avez spécifiée dans l'élément <Source> dans le cache spécifié dans l'élément <CacheResource>. Vous pouvez utiliser les éléments <CacheKey>, <Scope> et <Prefix> pour spécifier une clé que vous pouvez utiliser à partir de la règle <LookupCache> pour extraire la valeur. Utilisez l'élément <ExpirySettings> pour configurer le délai d'expiration de la valeur mise en cache.

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 ce cache, il vous suffit d'omettre l'élément <CacheResource>.

Limites de cache : des limites de cache diverses s'appliquent, telles que la taille du nom et des valeurs, le nombre total de caches, le nombre d'éléments dans un cache et l'expiration.

Pour plus d'informations sur le datastore sous-jacent, consultez la page Composants internes du cache.

À propos du chiffrement du cache

Apigee et Apigee hybrid (version 1.4 et ultérieure) : les données de cache et de KVM sont toujours chiffrées.

Codes d'erreur

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP Status Occurs when
policies.populatecache.EntryCannotBeCached 500 An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidCacheResourceReference This error occurs if the <CacheResource> element in the PopulateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. populatecache.POP-CACHE-1.failed = true

Example error response

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Example fault rule

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>