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 tiempo de ejecución.

La política Rellenar caché se ha diseñado para escribir entradas en una caché de uso general a corto plazo. Se usa junto con la política Lookup Cache (para leer entradas de caché) y la política Invalidate Cache (para invalidar entradas).

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

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

Referencia de elemento

A continuación, 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 superiores de la política:

Atributo	Descripción	Predeterminado	Presencia
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. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.	N/A	Obligatorio
continueOnError	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual	falso	Opcional
enabled	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.	true	Opcional
async	Este atributo está obsoleto.	falso	Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>

Predeterminado	N/A Si omite este elemento, se usará el valor del atributo name de la política.
Presencia	Opcional
Tipo	Cadena

Elemento <CacheKey>

Configura un puntero único a un fragmento de datos almacenado en la caché.

Las claves de caché tienen un tamaño máximo de 2 KB.

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

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

<CacheKey> crea el nombre de cada fragmento de datos almacenado en la caché.

En el tiempo de ejecución, los valores de <KeyFragment> se anteponen al valor del elemento <Scope> o al valor de <Prefix>. Por ejemplo, lo siguiente da como resultado 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>

Para ello, usa el elemento <CacheKey> junto con <Prefix> y <Scope>. Para obtener más información, consulta el artículo Trabajar con claves de caché.

Elemento <CacheResource>

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

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

<CacheResource>cache_to_use</CacheResource>

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

Para obtener más información sobre cómo configurar las 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 a la que se le va a quitar la referencia con el atributo ref o un valor fijo.

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

Valor predeterminado:	N/A
Presencia:	Cero o más
Tipo:	N/A

En el tiempo de ejecución, Apigee crea la clave de caché añadiendo al principio el valor obtenido del elemento <Scope> o del elemento <Prefix> a una concatenación de los valores resueltos de cada uno de los elementos <KeyFragment>. Para obtener más información, consulta el artículo Trabajar con claves de caché.

Atributos

Atributo	Tipo	Predeterminado	Obligatorio	Descripción
ref	cadena		No	La variable de la que se va a obtener el valor. No debe usarse si este elemento contiene un valor literal.

Elemento <CacheKey>/<Prefix>

Especifica un valor fijo que se usará como prefijo de clave de caché.

<Prefix>prefix_string</Prefix>

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

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

En el tiempo de ejecución, Apigee crea la clave de caché añadiendo al principio el valor obtenido del elemento <Scope> o del elemento <Prefix> a una concatenación de los valores resueltos de cada uno de los elementos <KeyFragment>. Para obtener más información, consulta el artículo Trabajar con claves de caché.

Elemento <ExpirySettings>

Especifica cuándo debe caducar 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>

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

Elementos secundarios de <ExpirySettings>

Usa exactamente un elemento secundario. En la siguiente tabla se describen los elementos secundarios de <ExpirySettings>:

Elemento secundario	Descripción
<TimeoutInSeconds>	Número de segundos tras los cuales debe caducar una entrada de caché. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Este elemento sustituye al elemento TimeoutInSec, que ya no se usa.
<ExpiryDate>	Especifica la fecha en la que debe caducar una entrada de caché. Especifica una cadena con el formato mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Si la fecha especificada es anterior a la actual, la política aplicará el tiempo de vida máximo a la entrada almacenada en caché. El máximo es de 30 días.
<TimeOfDay>	Especifica la hora del día en la que debe caducar una entrada de caché. Especifica una cadena con el formato HH:mm:ss, donde HH representa la hora en un reloj de 24 horas, en la zona horaria UTC. Por ejemplo, 14:30:00 significa las 2:30 de la tarde. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Notas: Especifica las horas en la zona horaria Tiempo Universal Coordinado (UTC). La notación de la hora de llenado de la caché sigue la notación de fecha estándar internacional definida en el estándar internacional ISO 8601.

Solo debe especificar uno de los elementos secundarios posibles. Si especificas varios elementos, el orden de precedencia es el siguiente:TimeoutInSeconds, ExpiryDate y TimeOfDay.

Con cada uno de los elementos secundarios de <ExpirySettings> anteriores, si especifica el atributo opcional ref en el elemento secundario, la política recuperará el valor de vencimiento de la variable de contexto con el nombre indicado. 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 para crear un prefijo para una clave de caché cuando no se proporciona un elemento <Prefix> en el elemento <CacheKey>.

<Scope>scope_enumeration</Scope>

Valor predeterminado:	"Exclusivo"
Presencia:	Opcional
Tipo:	Cadena

El ajuste <Scope> determina una clave de caché que se antepone según el valor de <Scope>. Por ejemplo, una clave de caché tendría el siguiente formato cuando el ámbito se definiera como Exclusive:

orgName__envName__apiProxyName__proxy|TargetName__ [ serializedCacheKey ]

Si hay un elemento <Prefix> en <CacheKey>, este sustituye al valor del elemento <Scope>. Los valores válidos incluyen las enumeraciones que se indican a continuación.

Para ello, usa el elemento <Scope> junto con <CacheKey> y <Prefix>. Para obtener más información, consulta el artículo Trabajar con claves de caché.

Valores aceptables

Global	La clave de caché se comparte entre todos los proxies de API implementados en el entorno. La clave de caché se antepone con el formato nombreOrganización __ nombreEntorno __. Si define una entrada <CacheKey> con <KeyFragment> apiAccessToken y un <Global> scope, cada entrada se almacena como orgName__envName__apiAccessToken, seguido del valor serializado del token de acceso. En el caso de un proxy de API implementado en un entorno llamado "test" de una organización llamada "apifactory", los tokens de acceso se almacenarían en la siguiente clave de caché: apifactory__test__apiAccessToken.
Application	El nombre del proxy de API se usa como prefijo. La clave de caché se antepone con el formato orgName__envName__apiProxyName.
Proxy	La configuración de ProxyEndpoint se usa como prefijo. La clave de caché se antepone con el formato orgName__envName__apiProxyName__proxyEndpointName .
Target	La configuración de TargetEndpoint se usa como prefijo. Clave de caché antepuesta con el formato orgName__envName__apiProxyName__targetEndpointName .
Exclusive	Predeterminado. Es la más específica y, por lo tanto, presenta un riesgo mínimo de colisiones de espacios de nombres en una caché determinada. El prefijo puede tener dos formas: Si la política se adjunta al flujo ProxyEndpoint, el prefijo tendrá el formato ApiProxyName_ProxyEndpointName. Si la política se adjunta en TargetEndpoint, el prefijo tiene el formato ApiProxyName_TargetName. Clave de caché con el prefijo en el formato orgName__envName__apiProxyName__proxyNameITargetName Por ejemplo, la cadena completa podría tener este aspecto: apifactory__test__weatherapi__default__apiAccessToken .

Elemento <Source>

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

<Source>source_variable</Source>

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	Cadena

Notas:

• Los objetos JSON se almacenan exclusivamente en la caché en memoria (L1).
• Si tienes intención de almacenar en caché estos objetos en la caché persistente (L2), te recomendamos que los serialices en formato cadena.
• Si sigues esta práctica, podrás utilizar la caché de nivel 2 de forma eficaz y maximizar la eficiencia del almacenamiento en caché.
• Para obtener más información, consulta Internos de la caché.
  

Notas de uso

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

El almacenamiento en caché de uso general con las políticas PopulateCache, LookupCache e InvalidateCache utiliza una caché que configures o una caché compartida que se incluye de forma predeterminada. En la mayoría de los casos, la caché compartida subyacente debería satisfacer sus necesidades. Para usar esta caché, solo tienes que omitir el elemento <CacheResource>.

Límites de la caché: se aplican varios límites de la caché , como el tamaño del nombre y del valor, el número total de cachés, el número de elementos de una caché y la caducidad.

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

Acerca del cifrado de caché

Apigee y Apigee hybrid (versión 1.4 y posteriores): los datos de caché y KVM siempre están cifrados.

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>