Política PopulateCache

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

Consulta la documentación de Apigee Edge.

La política PopulateCache 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__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__proxyEndpointName .
Target	La configuración TargetEndpoint se usa como prefijo. La clave de caché se antepone en el formato orgName__envName__apiProxyName__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__proxyNameITargetName Por ejemplo, la string completa podría verse de la siguiente manera: apifactory__test__weatherapi__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 error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Código de fallo	Estado de HTTP	Se produce cuando
policies.populatecache.EntryCannotBeCached	500	No se puede almacenar en caché una entrada. El objeto de mensaje que se va a almacenar en caché no es una instancia de una clase serializable.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nota: ¿Necesitas ayuda para resolver un error? En la columna Solución, haz clic en para obtener información detallada sobre cómo solucionar el problema.

Nombre del error	Causa	Solucionar
InvalidCacheResourceReference	Este error se produce si el elemento <CacheResource> de la política PopulateCache tiene asignado un nombre que no existe en el entorno en el que se está implementando el proxy de API.
CacheNotFound	La caché especificada en el elemento <CacheResource> no existe.

Variables de error

Estas variables se definen cuando esta política activa un error. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Variables	Dónde	Ejemplo
fault.name="fault_name"	fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	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"
    }
  }
}

Regla de fallo de ejemplo

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