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

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

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 implica las 2:30 de la tarde. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Notas: Especifique 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.

En cada uno de los elementos secundarios de <ExpirySettings> mencionados anteriormente, 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 define 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 en el formato orgName__envName__apiProxyName__targetEndpointName .
Exclusive	Predeterminado. Es la opción 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 tendrá 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 configuras 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

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>