Política PopulateCache

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X.
información

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

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

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.

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

falso Obsoleta

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

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia 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 Crea y edita una caché de entorno.

Elemento <CacheKey>/<KeyFragment>

Especifica un valor que se debe incluir en la clave de caché lo que crea un espacio de nombres para hacer coincidir las solicitudes con las respuestas almacenadas en caché.

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

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

N/A

Puede ser una clave (un nombre estático que proporcionas) o un valor (un conjunto de entradas dinámicas mediante la referencia de una variable). Todos los fragmentos especificados combinados (más el prefijo) se concatenan para crear la clave de caché.

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

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

Atributos

Atributo Tipo Predeterminada 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

Usa este valor en lugar de <Scope> cuando quieras especificar tu propio valor en lugar de un valor enumerado <Scope>. Si se define, <Prefix> antepone el valor de la clave de caché para las entradas escritas en la caché. Un valor de elemento <Prefix> anula un valor de elemento <Scope>.

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

Elemento <ExpirySettings>

Especifica cuándo debe vencer una entrada de caché. Cuando está presente, <TimeoutInSeconds> anula <TimeOfDay> y <ExpiryDate>.

<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 cadena con el formato HH:mm:ss, donde HH representa la en un formato de 24 horas, en la zona horaria UTC. Por ejemplo, 14:30:00 implica 2:30 de la tarde

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

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

Con cada uno de los elementos secundarios anteriores de <ExpirySettings>, Si especificas el atributo opcional ref en el elemento secundario, la política Recupera 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

predeterminada. 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 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 AutocompleteCache, la política LookupCache y la política InvalidateCache una caché que configures o una compartida que se incluya 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é. Para obtener más información sobre la configuración cachés, consulta Cómo crear y editar una la caché del entorno.

Información sobre la encriptación de caché

Edge para la nube pública: la caché se encripta solo en PCI- y compatibles con la HIPAA. organizaciones. La encriptación de esas organizaciones se configura durante el aprovisionamiento de estas.

Códigos de error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

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>