Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da Apigee Edge.
Armazena dados de recursos de back-end em cache, reduzindo o número de solicitações para o recurso. Como os aplicativos fazem solicitações para o mesmo URI, você pode usar essa política para retornar respostas armazenadas em cache em vez de encaminhar essas solicitações ao servidor de back-end. A política ResponseCache pode melhorar o desempenho da API por meio da latência reduzida e do tráfego de rede.
Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.
É provável que você considere ResponseCache mais útil quando os dados de back-end usados pela API são atualizados apenas periodicamente. Por exemplo, você tem uma API que expõe os dados do relatório meteorológico atualizados apenas a cada dez minutos. Usando o ResponseCache para retornar respostas armazenadas em cache entre atualizações, é possível diminuir o número de solicitações que alcançam o back-end. Isso também reduz o número de saltos de rede.
Para o armazenamento em cache de curto prazo e uso geral, aplique a política PopulateCache. Ela é usada em conjunto com as políticas LookupCache (para ler entradas de cache) e InvalidateCache (para invalidar entradas).
Assista ao vídeo a seguir para ver uma introdução à política de cache de resposta.
Amostras
Cache de 10 minutos
Esta amostra mostra como manter as respostas em cache mantidas por 10 minutos.
Imagine que você tem uma API no seguinte URL:
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
Você está usando o parâmetro de consulta w
como uma chave de cache. A Apigee verifica o
valor do parâmetro de consulta w
sempre que uma solicitação é recebida. Se uma resposta válida (ou
seja, não expirada) estiver presente no cache, a mensagem de resposta armazenada em cache será
retornada ao cliente solicitante.
Agora imagine que você tem uma política ResponseCache configurada da seguinte maneira.
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
Quando a proxy da API recebe pela primeira vez uma mensagem de solicitação para o seguinte URL, a resposta é armazenada em cache. Na segunda solicitação, em 10 minutos, ocorre uma consulta de cache. A resposta em cache é retornada ao app sem nenhuma solicitação encaminhada ao serviço de back-end.
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
Ignorar pesquisa de cache
O exemplo a seguir mostra como fazer com que a pesquisa em cache seja ignorada e atualizado o cache. Veja também este vídeo sobre o uso do SkipCacheLookup.
A condição opcional SkipCacheLookup (se configurada) é avaliada no caminho da solicitação. Se a condição for avaliada como verdadeira, a pesquisa de cache será ignorada e o cache será atualizado.
Um uso comum da atualização condicional do cache é uma condição que define um cabeçalho HTTP específico para que a condição seja avaliada como verdadeira. Um aplicativo cliente com script pode ser configurado para enviar periodicamente uma solicitação com o cabeçalho HTTP apropriado, causando explicitamente a atualização do cache de resposta.
Por exemplo, imagine uma chamada para uma API no URL a seguir:
'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"
Agora imagine a seguinte política ResponseCache configurada nesse proxy. Observe que a condição skip-cache é definida como verdadeira.
<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 mais informações sobre as condições, consulte Variáveis e condições do fluxo.
Referência de elemento
A referência de elemento descreve os elementos e atributos da 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">
A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:
Atributo | Descrição | Padrão | Presence |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
false | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
false | Descontinuado |
Elemento <DisplayName>
Use em conjunto com o atributo name
para rotular a política no
editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
<DisplayName>Policy Display Name</DisplayName>
Padrão |
N/A Se você omitir esse elemento, será usado o valor do atributo |
---|---|
Presence | Opcional |
Tipo | String |
Elemento <CacheKey>
Configura um ponteiro exclusivo para um conjunto de dados armazenados no cache.
As chaves de cache são limitadas a um tamanho de 2 KB.
<CacheKey> <Prefix>string</Prefix> <KeyFragment ref="variable_name" /> <KeyFragment>literal_string</KeyFragment> </CacheKey>
Padrão: |
N/A |
Presença: |
Obrigatório |
Tipo: |
N/A |
<CacheKey>
constrói o nome de cada dado armazenado no cache.
A chave geralmente é definida usando um valor dos cabeçalhos de entidade ou os parâmetros de consulta. Nesses casos, você faria
com que o atributo ref do elemento especifique uma variável contendo o valor da chave.
No ambiente de execução, os valores <KeyFragment>
são prefixados com o
valor do elemento <Scope>
ou <Prefix>
. Por exemplo, o
seguinte resultado gera uma chave de cache de
UserToken__apiAccessToken__
<value_of_client_id>:
<CacheKey> <Prefix>UserToken</Prefix> <KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" /> </CacheKey>
Use o elemento <CacheKey>
em conjunto com
<Prefix>
e <Scope>
. Para mais informações, consulte Como trabalhar com chaves de cache.
Elemento <CacheLookupTimeoutInSeconds>
Especifica o número de segundos após o qual uma pesquisa de cache mal-sucedida será considerada uma ausência de cache. Se isso ocorrer, o fluxo será retomado no caminho de ausência no cache.
<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>
Padrão: |
30 |
Presença: |
Opcional |
Tipo: |
Número inteiro |
Elemento <CacheResource>
Especifica o cache em que as mensagens devem ser armazenadas. Omita esse elemento para usar o cache
compartilhado incluído. Especifique um CacheResource
pelo nome se quiser limpar
administrativamente as entradas contidas no cache. Para mais informações, consulte API Caches.
<CacheResource>cache_to_use</CacheResource>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Elemento <CacheKey>/<KeyFragment>
Especifica um valor que deve ser incluído na chave de cache, criando um namespace para as solicitações correspondentes às respostas em cache.
<KeyFragment ref="variable_name"/> <KeyFragment>literal_string</KeyFragment>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
N/A |
Pode ser uma chave (um nome estático fornecido) ou um valor (uma entrada dinâmica definida por uma referência a uma variável). Todos os fragmentos especificados combinados (além do prefixo) são concatenados para criar a chave de cache.
<KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" />
Use o elemento <KeyFragment>
em conjunto com
<Prefix>
e <Scope>
. Para mais informações, consulte Como trabalhar com chaves de cache.
Atributos
Atributo | Tipo | Padrão | Obrigatório | Descrição |
---|---|---|---|---|
ref | string | Não |
A variável da qual conseguir o valor. Não pode ser usado se esse elemento contiver um valor literal. |
Elemento <CacheKey>/<Prefix>
Especifica um valor para usar como prefixo da chave de cache.
<Prefix>prefix_string</Prefix>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Use esse valor em vez de <Scope>
quando quiser especificar seu próprio valor em vez de um valor enumerado com <Scope>
. Se definido, <Prefix>
precede o valor da chave de cache das entradas gravadas no cache. Um valor de elemento <Prefix>
modifica um valor de elemento <Scope>
.
Use o elemento <Prefix>
em conjunto com
<CacheKey>
e <Scope>
. Para mais informações, consulte Como trabalhar com chaves de cache.
Elemento <ExcludeErrorResponse>
Atualmente, essa política armazena em cache as respostas HTTP com qualquer código de status possível. Isso significa que as respostas de sucesso e erro são armazenadas em cache. Por exemplo, as respostas com os códigos de status 2xx e 3xx são armazenadas em cache por padrão.
Defina este elemento como true
se você não quiser armazenar as respostas
de destino em cache com códigos de status de erro HTTP. Somente respostas com códigos de status de 200 a 205 serão
armazenadas em cache se o elemento for verdadeiro. Esses são os únicos códigos de status HTTP que a Apigee conta como
códigos de sucesso e não é possível alterar essa associação.
Para uma discussão sobre padrões de ResponseCache em que esse elemento é útil, consulte Introdução aos antipadrões.
<ExcludeErrorResponse>true</ExcludeErrorResponse>
Padrão: |
false |
Presença: |
Opcional |
Tipo: |
Booleano |
Elemento <ExpirySettings>
Especifica quando uma entrada de cache expira. Quando presente, <TimeoutInSeconds>
modifica <TimeOfDay>
e <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>
Padrão: |
N/A |
Presença: |
Obrigatório |
Tipo: |
N/A |
Elemento <ExpirySettings>/<ExpiryDate>
Especifica a data em que uma entrada de cache expira. Use o formulário mm-dd-yyyy
.
Quando presente, o irmão deste elemento, <TimeoutInSeconds>
, modifica
<ExpiryDate>
.
<ExpirySettings> <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate> </ExpirySettings>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Atributos
<ExpiryDate ref="" />
Atributo | Descrição | Padrão | Presence | Tipo |
---|---|---|---|---|
ref |
A variável da qual conseguir o valor. Não pode ser usado se esse elemento contiver um valor literal. |
N/A | Opcional | String |
Elemento <ExpirySettings>/<TimeOfDay>
A hora do dia em que uma entrada de cache expira. Use o formulário hh:mm:ss
.
Quando presente, o irmão deste elemento, <TimeoutInSeconds>
, modifica
<TimeOfDay>
.
Insira a hora do dia no formato HH:mm:ss, em que HH representa a hora em um relógio de 24 horas. Por exemplo, 14:30:00 por 2:30 à tarde.
Para a hora do dia, a localidade e o fuso horário padrão serão diferentes dependendo de onde o código está sendo executado (que não é conhecido quando você configura a política).
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descrição | Padrão | Presence | Tipo |
---|---|---|---|---|
ref | Variável com o valor do prazo de validade. | N/A | Opcional | String |
Elemento <ExpirySettings>/<TimeoutInSec>
O número de segundos após o qual uma entrada de cache expira.
Elemento <ExpirySettings>/<TimeoutInSeconds>
O número de segundos após o qual uma entrada de cache expira. Quando presente, esse elemento
modifica os irmãos, <TimeOfDay>
e <ExpiryDate>
.
<ExpirySettings> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> </ExpirySettings>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descrição | Padrão | Presence | Tipo |
---|---|---|---|---|
ref | Variável com o valor de tempo limite. |
N/A
|
Opcional | String |
Elemento <Scope>
Enumeração usada para construir um prefixo para uma chave de cache quando um elemento
<Prefix>
não é fornecido no elemento <CacheKey>
.
<Scope>scope_enumeration</Scope>
Padrão: |
"Exclusivo" |
Presença: |
Opcional |
Tipo: |
String |
A configuração <Scope>
determina uma chave de cache que é anexada de acordo com
o valor <Scope>
. Por exemplo, uma chave de cache assume a seguinte forma quando
o escopo é definido como Exclusive
:
orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [
serializedCacheKey ].
Se um elemento <Prefix>
estiver presente em <CacheKey>
, ele
substituirá um valor de elemento <Scope>
. Os valores válidos incluem as enumerações
abaixo.
Use o elemento <Scope>
em conjunto com
<CacheKey>
e <Prefix>
. Para mais informações, consulte Como trabalhar com chaves de cache.
Valores aceitáveis
Valor do escopo | Descrição |
---|---|
Global |
A chave de cache é compartilhada em todos os proxies de API implantados no ambiente. A chave de cache é precedida no formato orgName __ envName __. Se você definir uma entrada |
Application |
Nome do proxy da API é usado como prefixo. A chave de cache tem o formato orgName__envName__apiProxyName. |
Proxy |
A configuração do ProxyEndpoint é usada como prefixo. A chave de cache é precedida no formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName . |
Target |
A configuração TargetEndpoint é usada como prefixo. Chave do cache com o formato orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName . |
Exclusive |
Padrão. Este é o mais específico e, portanto, apresenta o risco mínimo de colisões de namespaces em um determinado cache. O prefixo estará em um destes dois formatos:
Chave de cache no formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName Por exemplo, a string completa pode ter esta aparência: apifactory__test__weatherapi__16__default__apiAccessToken |
Elemento <SkipCacheLookup>
Define uma expressão que, se for avaliada como verdadeira no ambiente de execução, especifica que a pesquisa de cache
precisa ser ignorada e o cache precisa ser atualizado. Veja também
o vídeo sobre como usar a política ResponseCache, que explica o uso de SkipCacheLookup
.
<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
No exemplo a seguir, se a variável bypass-cache estiver definida como verdadeira em um cabeçalho de entrada, a pesquisa do cache será ignorada e o cache será atualizado.
<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
Elemento <SkipCachePopulation>
Define uma expressão que, se for avaliada como verdadeira no ambiente de execução, especifica que uma gravação no
cache precisa ser ignorada. Assista também a este
vídeo que explica o uso de SkipCachePopulation
.
<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
O exemplo a seguir ignoraria a gravação no cache se o código de status da resposta fosse 400 ou superior:
<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>
Elemento <UseAcceptHeader>
Defina como true
para que uma chave de cache da entrada de cache de resposta fique anexada aos valores de
cabeçalhos de resposta Accept.
A Apigee usa os cabeçalhos de solicitação Accept
, Accept-Encoding
, Accept-Language
e Accept-Charset
ao calcular a chave de cache. Essa abordagem
impede que um cliente receba um tipo de mídia que ele não pediu.
Por exemplo, considere se duas solicitações vierem do mesmo URL, onde a primeira solicitação aceita gzip e a segunda não. A primeira solicitação será armazenada em cache, e a entrada em cache, provavelmente, será uma resposta compactada em gzip. A segunda solicitação lê o valor em cache e pode retornar uma entrada compactada em gzip para um cliente que não é capaz de ler o gzip.
Consulte Como configurar uma chave de cache para saber mais.
<UseAcceptHeader>false</UseAcceptHeader>
Padrão: |
false |
Presença: |
Opcional |
Tipo: |
Booleano |
Elemento <UseResponseCacheHeaders>
Defina como true
para que os cabeçalhos de resposta HTTP sejam considerados ao definir o "time to
live" (TTL) da resposta no cache. Quando verdadeiro, a Apigee considera os valores dos
seguintes cabeçalhos de resposta, comparando os valores com aqueles definidos por
<ExpirySettings>
ao definir o tempo de vida:
Cache-Control s-maxage
Cache-Control max-age
Expires
Consulte Como configurar a expiração da entrada de cache para mais detalhes.
<UseResponseCacheHeaders>false</UseResponseCacheHeaders>
Padrão: |
false |
Presença: |
Opcional |
Tipo: |
Booleano |
Observações sobre uso
O tamanho máximo de cada objeto armazenado em cache é de 256 KB. Para informações detalhadas sobre como a Apigee processa o cache, consulte elementos do cache.
Por meio da configuração na política ResponseCache, você pode fazer com que a Apigee inclua cabeçalhos de resposta HTTP na configuração de expiração da entrada de cache e nas chaves de cache. Nesta seção, você pode usar a política com cabeçalhos para gerenciar a expiração e as chaves de cache.
Para saber mais sobre como a Apigee processa os cabeçalhos de resposta com a política ResponseCache, consulte compatibilidade com cabeçalhos de resposta HTTP.
Como configurar a expiração de entradas no cache
Assim como na política PopulateCache, é possível definir a expiração de uma entrada de cache de resposta (o tempo em que ela fica ativa) com o
elemento <ExpirySettings>
. Na política ResponseCache, você também pode fazer com que a Apigee
considere os cabeçalhos de resposta quando eles estiverem presentes.
Para usar cabeçalhos de resposta, defina o valor do elemento <UseResponseCacheHeaders>
como
verdadeiro. Essa configuração faz com que a Apigee considere os cabeçalhos de resposta, compare-os com o valor definido
por <ExpirySettings>
e use o valor mais baixo entre os dois. Ao
considerar os cabeçalhos de resposta, a Apigee escolhe o valor disponível conforme descrito
a seguir:
Por exemplo, imagine que uma resposta seja armazenada em cache com os seguintes valores:
- Nenhum valor
Cache-Control s-maxage
- Um valor
Cache-Control max-age
de 300 - Uma data
Expires
em três dias - Um valor
<ExpirySettings>
TimeoutInSeconds
de 600.
Nesse caso, o valor Cache-Control
max-age
seria usado para o
TTL porque é menor que o valor <ExpirySettings>
e porque não
há valor Cache-Control s-maxage
(que tem precedência sobre
max-age
).
Como configurar uma chave de cache
Assim como nas políticas de cache de uso geral, como a política PopulateCache, com
ResponseCache você usa os elementos <CacheKey>
e <Scope>
para
configurar a criação da chave de cache para entradas. Com o ResponseCache, você também pode tornar as chaves de cache
mais significativas, tendo cabeçalhos de resposta Accept como valores de chave.
Para informações gerais sobre a configuração de chaves de cache, consulte Como trabalhar com chaves de cache. Para
informações sobre como usar os cabeçalhos Accept, consulte <UseAcceptHeader>
.
Sobre a criptografia de cache
Apigee e Apigee híbrida (versão 1.4 e posterior): os dados de cache e KVM são sempre criptografados.
Variáveis de fluxo
As variáveis de fluxo predefinidas a seguir são preenchidas quando uma política ResponseCache é executada. Para mais informações sobre variáveis de fluxo, consulte a esta referência.
Variáveis | Tipo | Permissão | Descrição |
---|---|---|---|
responsecache.{policy_name}.cachename |
String | Somente leitura | Retorna o cache usado na política |
responsecache.{policy_name}.cachekey |
String | Somente leitura | Retorna a chave usada |
responsecache.{policy_name}.cachehit |
Booleano | Somente leitura | Verdadeiro se a execução da política for bem-sucedida |
responsecache.{policy_name}.invalidentry |
Booleano | Somente leitura | Verdadeiro se a entrada do cache não for válida |
Códigos de erro
Nesta seção, descrevemos as mensagens de erro e as variáveis de fluxo que são definidas quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para um proxy. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Prefixo do código de erro
N/A
Erros de execução
Essa política não gera erros de ambiente de execução.
Erros de implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
Nome do erro | Causa | Correção |
---|---|---|
InvalidTimeout |
Se o elemento <CacheLookupTimeoutInSeconds> de uma política ResponseCache estiver definida como um número negativo, a implantação do proxy da API falhará. |
build |
InvalidCacheResourceReference |
Esse erro ocorrerá se o elemento <CacheResource> na política ResponseCache estiver definido como um nome que não exista no ambiente em que o proxy de API está sendo implantado. |
build |
ResponseCacheStepAttachmentNotAllowedReq |
Este erro ocorre quando a mesma política ResponseCache está anexada a vários caminhos de solicitação em qualquer fluxo de um proxy de API. |
build |
ResponseCacheStepAttachmentNotAllowedResp |
Esse erro ocorre quando a mesma política ResponseCache está anexada a vários caminhos de resposta em qualquer fluxo de um proxy de API. |
build |
InvalidMessagePatternForErrorCode |
Esse erro ocorre quando o elemento <SkipCacheLookup> ou <SkipCachePopulation>
em uma política ResponseCache tem uma condição inválida. |
build |
CacheNotFound |
Esse erro ocorre quando o cache específico mencionado na mensagem de erro não tiver sido criado em um componente de processador de mensagens específico. | build |
Variáveis de falha
N/A
Exemplo de resposta de erro
N/A
Esquema
Cada tipo de política é definido por um esquema XML (.xsd
). Para referência, os esquemas de política
estão disponíveis no GitHub.