Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de Apigee Edge.
Almacena en caché los datos de un recurso de backend, lo que reduce la cantidad de solicitudes que se le envían al recurso. Como las apps realizan solicitudes al mismo URI, puedes usar esta política para mostrar respuestas almacenadas en caché en lugar de reenviar esas solicitudes al servidor de backend. La política ResponseCache puede mejorar el rendimiento de la API mediante una latencia reducida y el tráfico de red.
Esta política es una política extensible, y el uso de esta política 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.
Es probable que ResponseCache sea más útil cuando los datos de backend que usa tu API se actualizan solo de forma periódica. Por ejemplo, imagina que tienes una API que expone los datos del informe del clima actualizados solo cada diez minutos. Cuando usas ResponseCache para mostrar respuestas almacenadas en caché entre las actualizaciones, puedes reducir la cantidad de solicitudes que llegan al backend. Esto también reduce el número de saltos de red.
Para el almacenamiento en caché a corto plazo de uso general, considera usar la política de PopulateCache. Esa política se usa junto con la política de LookupCache (para leer entradas de caché) y la política de InvalidateCache (para invalidar entradas).
Mira el siguiente video para obtener una introducción a la política de caché de respuesta.
Ejemplos
Caché de 10 minutos
En este ejemplo, se muestra cómo se conservan las respuestas en caché durante 10 minutos.
Imagina que tienes una API en la siguiente URL:
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
Usas el parámetro de búsqueda w
como clave de caché. Apigee verifica el valor del parámetro de búsqueda w
cada vez que se recibe una solicitud. Si una respuesta válida (es decir, no vencida) está presente en la caché, el mensaje de respuesta almacenado en caché se muestra al cliente que la solicita.
Ahora, supongamos que tienes una política ResponseCache configurada de la siguiente manera.
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
La primera vez que el proxy de API recibe un mensaje de solicitud para la siguiente URL, la respuesta se almacena en caché. En la segunda solicitud, en un plazo de 10 minutos, se produce una búsqueda de caché; la respuesta se almacena en caché en la app sin que se reenvíe una solicitud al servicio de backend.
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
Omite la búsqueda en caché
En el siguiente ejemplo, se muestra cómo omitir la búsqueda en caché y hacer que se actualice la caché. Consulta también este video sobre el uso de SkipCacheLookup.
La condición opcional SkipCacheLookup (si está configurada) se evalúa en la ruta de la solicitud. Si la condición se evalúa como verdadera, se omite la búsqueda de la caché y se actualiza la caché.
Un uso común de la actualización de la caché condicional es una condición que define un encabezado HTTP específico que hace que la condición se evalúe como verdadera. Se puede configurar una aplicación cliente con secuencia de comandos para enviar de forma periódica una solicitud con el encabezado HTTP adecuado, lo que genera que la caché de respuesta se actualice de forma explícita.
Por ejemplo, imagina una llamada a una API en la siguiente URL:
'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"
Ahora, imaginemos que la siguiente política ResponseCache está configurada en ese proxy. Ten en cuenta que la condición bypass-cache se configura como verdadera.
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <!-- Explicitly refresh the cached response --> <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
Para obtener más información sobre las condiciones, consulta Variables y condiciones de flujo.
Referencia del elemento
En la referencia del elemento, se describen los elementos y los atributos de la política.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1"> <DisplayName>Response Cache 1</DisplayName> <Properties/> <CacheKey> <Prefix/> <KeyFragment ref="request.uri" /> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <ExpiryDate/> <TimeOfDay/> <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds> </ExpirySettings> <CacheResource>cache_to_use</CacheResource> <CacheLookupTimeoutInSeconds/> <ExcludeErrorResponse/> <SkipCacheLookup/> <SkipCachePopulation/> <UseAcceptHeader/> <UseResponseCacheHeaders/> </ResponseCache>
Atributos <ResponseCache>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
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 De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
false | Opcional |
enabled |
Configúralo como Configúralo como |
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 |
---|---|
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é.
A menudo, la clave se configura mediante un valor de los encabezados de entidad o los parámetros de búsqueda. En esos casos, el atributo ref del elemento especifica una variable que contiene el valor de la clave.
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<CacheLookupTimeoutInSeconds>
Especifica la cantidad de segundos después de los cuales una búsqueda en caché incorrecta se considerará un error de caché. Si esto ocurre, el flujo se reanuda en la ruta de acceso del error de caché.
<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>
Predeterminado: |
30 |
Presencia: |
Opcional |
Tipo: |
Entero |
Elemento <CacheResource>
Especifica la caché en la que se deben almacenar los mensajes. Omite este elemento para usar la caché compartida que se incluye. Debes especificar un CacheResource
por nombre si deseas borrar de manera administrativa las entradas contenidas en la caché. Para obtener más información, consulta API de Cachés.
<CacheResource>cache_to_use</CacheResource>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
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 | 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 |
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 <ExcludeErrorResponse>
Esta política puede almacenar en caché respuestas HTTP con cualquier código de estado. Esto significa que tanto las respuestas correctas como las de error se pueden almacenar en caché, incluidos los códigos de estado 2xx y 3xx.
Establece este elemento en true
(predeterminado) para excluir las respuestas de error. Configúralo en false
si no deseas excluir las respuestas de destino de la caché con códigos de estado de error de HTTP.
Si deseas ver un análisis de los patrones de caché de respuesta en el que este elemento es útil, consulta Introducción a los antipatrones.
<ExcludeErrorResponse>true</ExcludeErrorResponse>
Predeterminado: |
true |
Presencia: |
Opcional |
Tipo: |
Booleano |
Elemento <ExpirySettings>
Especifica cuándo debe vencer una entrada de caché. Cuando está presente, <TimeoutInSeconds>
anula <TimeOfDay>
y <ExpiryDate>
.
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> <ExpiryDate ref="date_variable">expiration_date</ExpiryDate> </ExpirySettings>
Predeterminado: |
N/A |
Presencia: |
Obligatorio |
Tipo: |
N/A |
Elemento<ExpirySettings>/<ExpiryDate>
Especifica la fecha en la que debe vencer una entrada de caché. Usa el formato mm-dd-yyyy
.
Cuando está presente, el mismo nivel del elemento, <TimeoutInSeconds>
, anula <ExpiryDate>
.
<ExpirySettings> <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate> </ExpirySettings>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
Atributos
<ExpiryDate ref="" />
Atributo | Descripción | Predeterminado | Presence | Tipo |
---|---|---|---|---|
ref |
Variable de la que se obtiene el valor No debe usarse si este elemento contiene un valor literal. |
N/A | Opcional | String |
Elemento <ExpirySettings>/<TimeOfDay>
La hora a la que debe vencer una entrada de caché. Usa el formato hh:mm:ss
.
Cuando está presente, el mismo nivel del elemento, <TimeoutInSeconds>
, anula <TimeOfDay>
.
Ingresa la hora del día con el formato HH:mm:ss, en el que HH representa la hora en un reloj de 24 horas. Por ejemplo, 14:30:00 por 2:30 en la tarde.
La hora, la configuración regional y la zona horaria predeterminadas, variarán según el lugar en que se ejecute el código (lo que no se sabe cuándo se configura la política).
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descripción | Predeterminado | Presence | Tipo |
---|---|---|---|---|
ref | Variable con el valor de tiempo de vencimiento | N/A | Opcional | String |
Elemento <ExpirySettings>/<TimeoutInSec>
Cantidad de segundos después de los cuales debe vencer una entrada de caché.
Elemento <ExpirySettings>/<TimeoutInSeconds>
Cantidad de segundos después de los cuales debe vencer una entrada de caché. Cuando está presente, este elemento anula los elementos de mismo nivel, <TimeOfDay>
y <ExpiryDate>
.
<ExpirySettings> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> </ExpirySettings>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descripción | Predeterminado | Presence | Tipo |
---|---|---|---|---|
ref | Variable con el valor de tiempo de espera. |
N/A
|
Opcional | String |
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é tomaría el siguiente formato cuando el alcance se configura como 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
Valor del permiso | Descripción |
---|---|
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 |
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:
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<SkipCacheLookup>
Define una expresión que, si se evalúa como verdadera en el entorno de ejecución, especifica que la búsqueda en caché debe omitirse y la caché debe actualizarse. Consulta también Cómo usar el video de la política ResponseCache sobre el uso de SkipCacheLookup
.
<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
En el siguiente ejemplo, si la variable bypass-cache se configura como verdadera en un encabezado entrante, la búsqueda en caché se omite y la caché se actualiza.
<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
Elemento<SkipCachePopulation>
Define una expresión que, si se evalúa como verdadera en el entorno de ejecución, especifica que se debe omitir una escritura en la caché. Consulta también este video sobre el uso de SkipCachePopulation
.
<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>
Predeterminado: |
N/A |
Presencia: |
Opcional |
Tipo: |
String |
Por ejemplo, lo siguiente omitiría la escritura en caché si el código de estado de la respuesta fuera 400 o superior:
<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>
Elemento <UseAcceptHeader>
Configúralo como true
para agregar la clave de caché de la entrada de caché a los valores de los encabezados de aceptación de respuesta.
Apigee usa los encabezados de la solicitud Accept
, Accept-Encoding
, Accept-Language
y Accept-Charset
cuando calcula la clave de caché. En este enfoque, se evita que un cliente obtenga un tipo de medio que no solicitó.
Por ejemplo, considera si dos solicitudes provienen de la misma URL, en la que la primera solicitud acepta gzip y la segunda no. La primera solicitud se almacenará en caché y es probable que la entrada en caché sea respuesta en formato gzip. La segunda solicitud leerá el valor almacenado en caché y, luego, podrá mostrar una entrada comprimida a un cliente que no puede leer en formato gzip.
Consulta Configura una clave de caché para obtener más información.
<UseAcceptHeader>false</UseAcceptHeader>
Predeterminado: |
false |
Presencia: |
Opcional |
Tipo: |
Booleano |
Elemento <UseResponseCacheHeaders>
Configúralo como true
para que los encabezados de respuesta HTTP se consideren cuando se configure el “tiempo de actividad” (TTL) de la respuesta en la caché. Cuando es verdadero, Apigee considera los valores de los siguientes encabezados de respuesta y compara los valores con los que establece <ExpirySettings>
cuando se establece el tiempo de actividad:
Cache-Control s-maxage
Cache-Control max-age
Expires
Consulta Configura el vencimiento de entradas de caché para obtener más detalles.
<UseResponseCacheHeaders>false</UseResponseCacheHeaders>
Predeterminado: |
false |
Presencia: |
Opcional |
Tipo: |
Booleano |
Notas de uso
El tamaño máximo de cada objeto almacenado en caché es de 256 KB. (Para obtener información detallada sobre cómo Apigee procesa la caché, consulta Objetos internos de la caché).
A través de la configuración en la política ResponseCache, puedes hacer que Apigee incluya encabezados de respuesta HTTP en la configuración del vencimiento de la entrada y las claves de caché. En esta sección, se describe cómo puedes usar la política con encabezados para administrar el vencimiento y las claves de caché.
Para obtener más información sobre cómo Apigee maneja los encabezados de respuesta con la política ResponseCache, consulta Compatibilidad con los encabezados de respuesta HTTP.
Configura el tiempo de vencimiento de la entrada de caché
Al igual que con la política PopulateCache, puedes configurar el vencimiento de una entrada de caché de respuesta (su tiempo de actividad) con el elemento <ExpirySettings>
. En la política ResponseCache, también puedes hacer que Apigee considere los encabezados de respuesta cuando estén presentes.
Para usar encabezados de respuesta, debes configurar el valor del elemento <UseResponseCacheHeaders>
como verdadero. Esta configuración hace que Apigee considere los encabezados de respuesta, los compare con el valor establecido por <ExpirySettings>
y, luego, use el valor más bajo entre ambos. Cuando se consideran los encabezados de respuesta, Apigee elige el valor disponible como se describe a continuación:
Por ejemplo, imagina que una respuesta se almacena en caché con los siguientes valores:
- Sin valor
Cache-Control s-maxage
- Un valor
Cache-Control max-age
de 300 - Una fecha de
Expires
en tres días - Un valor
<ExpirySettings>
TimeoutInSeconds
de 600.
En este caso, el valor Cache-Control
max-age
se usará para el TTL porque es menor que el valor <ExpirySettings>
y porque no hay ningún valor Cache-Control s-maxage
(que tiene prioridad sobre max-age
).
Configura una clave de caché
Al igual que con las políticas de caché de uso general, como la política PopulateCache, con ResponseCache se usan elementos <CacheKey>
y <Scope>
a fin de configurar la creación de claves de caché para entradas de caché. Con ResponseCache, también puedes hacer que las claves de caché sean más significativas si incluyes encabezados de aceptación de respuestas adjuntos en los valores de las claves.
Si deseas obtener información para configurar claves de caché, consulta Trabaja con claves de caché. Si deseas obtener información sobre el uso de encabezados de aceptación, consulta <UseAcceptHeader>
.
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.
Variables de flujo
Las siguientes variables predefinidas de flujo se propagan cuando se ejecuta una política de ResponseCache. Para obtener más información sobre las variables de flujo, consulta Referencia de variables de flujo.
Variables | Tipo | Permiso | Descripción |
---|---|---|---|
responsecache.{policy_name}.cachename |
String | Solo lectura | Muestra la caché usada en la política |
responsecache.{policy_name}.cachekey |
String | Solo lectura | Muestra la clave usada |
responsecache.{policy_name}.cachehit |
Booleano | Solo lectura | Verdadero si la ejecución de la política es adecuada |
responsecache.{policy_name}.invalidentry |
Booleano | Solo lectura | Verdadero si la entrada de caché no es válida |
Códigos de error
En esta sección, se describen los mensajes de error y las variables de flujo que se configuran cuando esta política activa un error. Esta información es importante si deseas saber si desarrollas reglas de fallas para un proxy. Para obtener más información, consulta Lo que necesitas saber sobre errores de políticas y Controla fallas.
Prefijo del código de error
N/A
Errores de entorno de ejecución
Esta política no arroja ningún error de entorno de ejecución.
Errores en la implementación
Estos errores pueden generarse cuando implementas un proxy que contiene esta política.
Nombre del error | Causa | Corregir |
---|---|---|
InvalidTimeout |
Si el elemento <CacheLookupTimeoutInSeconds> de una política ResponseCache está configurado como un número negativo, la implementación del proxy de API falla. |
build |
InvalidCacheResourceReference |
Este error se genera si el elemento <CacheResource> en la política ResponseCache se configura como un nombre que no existe en el entorno en el que se implementa el proxy de API. |
build |
ResponseCacheStepAttachmentNotAllowedReq |
Este error se produce si la misma política ResponseCache se vincula con varias rutas de solicitud dentro de cualquier flujo de un proxy de API. |
build |
ResponseCacheStepAttachmentNotAllowedResp |
Este error se produce si la misma política ResponseCache se adjunta a varias rutas de respuesta dentro de cualquier flujo de un proxy de API. |
build |
InvalidMessagePatternForErrorCode |
Este error se produce si el elemento <SkipCacheLookup> o <SkipCachePopulation> en una política ResponseCache contiene una condición no válida. |
build |
CacheNotFound |
Este error se genera si la caché específica que se menciona en el mensaje de error no se creó en un componente específico del procesador de mensajes. | build |
Variables con fallas
N/A
Ejemplo de respuesta de error
N/A
Esquema
Un esquema XML (.xsd
) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.