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

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla	Estado de HTTP	Ocurre cuando
policies.populatecache.EntryCannotBeCached	500	Una entrada no se puede almacenar en caché. El objeto del mensaje que se almacena en caché no es una instancia de una clase que se pueda serializar.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
InvalidCacheResourceReference	Este error se genera si el elemento <CacheResource> en la política PopulateCache se configura como un nombre que no existe en el entorno en el que se implementa el proxy de API.
CacheNotFound	No existe la caché especificada en el elemento <CacheResource>.

Variables con fallas

Estas variables se establecen cuando esta política activa un error. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
fault.name="fault_name"	fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	populatecache.POP-CACHE-1.failed = true

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

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