Política PopulateCache

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Configura cómo se deben escribir los valores almacenados en caché en el entorno de ejecución.

La política de propagación de caché está diseñada para escribir entradas en una caché de uso general a corto plazo. Se usa junto con la política de LookupCache (para leer entradas de caché) y la política de InvalidateCache (para invalidar entradas).

Esta política es una política extensible, y el uso de esta puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Para almacenar en caché las respuestas de los recursos de backend, consulta la política de Response Cache.

Referencia del elemento

En la siguiente lista, se enumeran los elementos que puedes configurar en esta política.

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

Atributos <PopulateCache>

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Configuración predeterminada	Presence
name	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	false	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	false	Obsoleto

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Configuración predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presence	Opcional
Tipo	String

Elemento <CacheKey>

Configura un puntero único para un dato almacenado en la caché.

Las claves de caché se limitan a un tamaño de 2 KB.

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

Predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

<CacheKey> construye el nombre de cada dato almacenado en la caché.

En el entorno de ejecución, los valores <KeyFragment> están precedidos del valor del elemento <Scope> o el valor <Prefix>. Por ejemplo, lo siguiente genera una clave de caché de UserToken__apiAccessToken__<value_of_client_id>:

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

Debes usar el elemento <CacheKey> junto con <Prefix> y <Scope>. Para obtener más información, consulta Trabaja con claves de caché.

Elemento<CacheResource>

Especifica la caché en la que se deben almacenar los mensajes.

Omite este elemento por completo si esta política (y las políticas InvalidateCache y LookupCache correspondientes) usa la caché compartida incluida.

<CacheResource>cache_to_use</CacheResource>

Predeterminado:	N/A
Presencia:	Opcional
Tipo:	String

Para obtener más información sobre la configuración de cachés, consulta Almacenamiento en caché de uso general.

Elemento <CacheKey>/<KeyFragment>

Especifica un valor que se debe incluir en la clave de caché. Especifica una variable para quitar la referencia con el atributo ref o un valor fijo.

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

Predeterminado:	N/A
Presencia:	cero o más
Tipo:	N/A

En el entorno de ejecución, Apigee crea la clave de caché anteponiendo el valor obtenido del elemento <Scope> o el elemento <Prefix> a una concatenación de los valores resueltos de cada uno de los elementos <KeyFragment>. Para obtener más información, consulta Trabaja con claves de caché.

Atributos

Atributo	Tipo	Predeterminado	Obligatorio	Descripción
ref	string		No	Variable de la que se obtiene el valor No debe usarse si este elemento contiene un valor literal.

Elemento <CacheKey>/<Prefix>

Especifica un valor para usar como prefijo de clave de caché.

<Prefix>prefix_string</Prefix>

Predeterminado:	N/A
Presencia:	Opcional
Tipo:	String

Un elemento <Prefix> anula cualquier elemento <Scope>.

En el entorno de ejecución, Apigee crea la clave de caché anteponiendo el valor obtenido del elemento <Scope> o el elemento <Prefix> a una concatenación de los valores resueltos de cada uno de los elementos <KeyFragment>. Para obtener más información, consulta Trabaja con claves de caché.

Elemento <ExpirySettings>

Especifica cuándo debe vencer una entrada de caché.

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

Predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

Elementos secundarios de <ExpirySettings>

Usa exactamente un elemento secundario. En la siguiente tabla, se proporciona una descripción de los elementos secundarios de <ExpirySettings>:

Elemento secundario	Descripción
<TimeoutInSeconds>	Cantidad de segundos después de los cuales debe vencer una entrada de caché. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Este elemento reemplaza al elemento TimeoutInSec obsoleto.
<ExpiryDate>	Especifica la fecha en la que debe vencer una entrada de caché. Especifica una string con el formato mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Si la fecha especificada es anterior, la política aplicará el tiempo de actividad máximo a la entrada almacenada en caché. El máximo es de 30 días.
<TimeOfDay>	Especifica el momento del día en el que debe vencer una entrada de caché. Especifica una string con el formato HH:mm:ss, en el que HH representa la hora en un reloj de 24 horas en la zona horaria UTC. Por ejemplo, 14:30:00 implican 2:30 en la tarde. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Notas: Especifica las horas en la zona horaria Horario universal coordinado (UTC). Propaga la notación de tiempo de la caché de acuerdo con la notación de fechas estándar internacional definida en el estándar internacional ISO 8601.

Debes especificar solo uno de los elementos secundarios posibles. Si especificas varios elementos, el orden de prioridad es TimeoutInSeconds, ExpiryDate y TimeOfDay.

Con cada uno de los elementos secundarios anteriores de <ExpirySettings>, si especificas el atributo opcional ref en el elemento secundario, la política recuperará el valor de vencimiento de la variable de contexto con nombre. Si la variable no está definida, la política usa el valor de texto literal del elemento secundario.

Elemento <Scope>

Enumeración que se usa a fin de construir un prefijo para una clave de caché cuando no se proporciona un elemento <Prefix> en el elemento <CacheKey>.

<Scope>scope_enumeration</Scope>

Predeterminado:	“Exclusivo”
Presencia:	Opcional
Tipo:	String

La configuración <Scope> determina una clave de caché que se antepone según el valor <Scope>. Por ejemplo, una clave de caché podría tener el siguiente formato cuando el alcance se establece en Exclusive:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

Si un elemento <Prefix> está presente en <CacheKey>, sustituye un valor de elemento <Scope>. Los valores válidos incluyen las enumeraciones a continuación.

Debes usar el elemento <Scope> junto con <CacheKey> y <Prefix>. Para obtener más información, consulta Trabaja con claves de caché.

Valores aceptables

Global	La clave de caché se comparte en todos los proxies de API implementados en el entorno. La clave de caché se antepone en el formato orgName __ envName __. Si defines una entrada <CacheKey> con el apiAccessToken <KeyFragment> y un alcance <Global>, cada entrada se almacena como orgName__envName__apiAccessToken, seguida del valor serializado del token de acceso. Para un proxy de API implementado en un entorno llamado “test” en una organización llamada “apifactory”, los tokens de acceso se almacenarán en la siguiente clave de caché: apifactory__test__apiAccessToken.
Application	El nombre del proxy de la API se usa como prefijo. La clave de caché se antepone en el formato orgName__envName__apiProxyName.
Proxy	La configuración de ProxyEndpoint se usa como prefijo. La clave de caché se antepone en el formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName.
Target	La configuración TargetEndpoint se usa como prefijo. La clave de caché se antepone en el formato orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName.
Exclusive	Predeterminado. Este es el más específico, por lo tanto, representa el riesgo mínimo de colisiones de espacio de nombres dentro de una caché determinada. El prefijo es uno de estos dos formatos: Si la política se adjunta al flujo ProxyEndpoint, el prefijo tiene el formato ApiProxyName_ProxyEndpointName. Si se adjunta una política en TargetEndpoint, el prefijo tiene el formato ApiProxyName_TargetName. La clave de caché se antepone en el formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName Por ejemplo, la string completa podría verse de la siguiente manera: apifactory__test__weatherapi__16__default__apiAccessToken .

Elemento <Source>

Especifica la variable cuyo valor se debe escribir en la caché.

<Source>source_variable</Source>

Predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	String

Notas:

• Los objetos JSON se almacenan de forma exclusiva en la caché en memoria (L1).
• Si deseas almacenar en caché estos objetos en la caché persistente (L2), te recomendamos serializarlos en un formato de string.
• Si sigues esta práctica, puedes usar la caché L2 de manera eficaz y maximizar la eficiencia del almacenamiento en caché.
• Para obtener más información, consulta Objetos internos de la caché.
  

Notas de uso

Usa esta política para el almacenamiento en caché de uso general. En el entorno de ejecución, la política <PopulateCache> escribe los datos de la variable que especificaste en el elemento <Source> en la caché que especificaste en el elemento <CacheResource>. Puedes usar los elementos <CacheKey>, <Scope> y <Prefix> a fin de especificar una clave que puedes usar desde la política <LookupCache> para recuperar el valor. Usa el elemento <ExpirySettings> para configurar cuándo debe vencer el valor almacenado en caché.

El almacenamiento en caché de uso general con la política PopulateCache, la política LookupCache y la política InvalidateCache usan la caché que configuras o una caché compartida que se incluye de forma predeterminada. En la mayoría de los casos, la caché compartida subyacente debe satisfacer tus necesidades. Para usar esta caché, solo omite el elemento <CacheResource>.

Límites de caché: se aplican varios límites de caché, como el nombre y el tamaño del valor, la cantidad total de cachés, la cantidad de elementos en una caché y un vencimiento.

Para obtener más información sobre el almacén de datos subyacente, consulta Objetos internos de la caché.

Información sobre la encriptación de caché

Versiones de Apigee y Apigee Hybrid (1.4 y posteriores): Los datos de caché y KVM siempre se encriptan.

Códigos de error

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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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>