Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
![](https://docs.apigee.com/static/api-platform/images/icon_policy_traffic-management.jpg?authuser=0000&hl=pt)
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.
É 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, use a política de preenchimento de cache. Essa política é usada em conjunto com a Política de pesquisa de cache (para ler entradas de cache) e a Política de invalidação de cache (para invalidar entradas).
Assista a este vídeo 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. O Apigee Edge verifica
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 | Presença |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
falso | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
falso | Obsoleto |
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 |
---|---|
Presença | 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: |
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 que você quer que seja capaz de limpar administrativamente as entradas contidas no cache. Para mais informações, consulte Caches.
<CacheResource>cache_to_use</CacheResource>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Para mais informações sobre como configurar caches, consulte Como criar e editar um cache de ambiente.
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 o Edge conta como
"sucesso" e não é possível alterar essa associação.
Para ver uma discussão sobre os padrões de cache de resposta em que esse elemento é útil, consulte esta postagem da comunidade.
Observação: em uma versão futura (para ser determinada), a configuração padrão desse elemento será alterada para "true". Consulte os Notas de lançamento da Apigee para ver mais detalhes.
<ExcludeErrorResponse>true</ExcludeErrorResponse>
Padrão: |
falso |
Presença: |
Opcional |
Tipo: |
Booleanos |
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 | Presença | 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). Para mais informações sobre como configurar sua localidade, consulte Como criar e editar um cache de ambiente.
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descrição | Padrão | Presença | 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>
Observação: forneça um valor de tempo limite padrão para uso se a referência não receber um valor do
duration_variable
.
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Atributos
Atributo | Descrição | Padrão | Presença | 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 este vídeo sobre o uso do 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 sobre o uso da 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.
O Edge usa Accept
, Accept-Encoding
e Accept-Language
e cabeçalhos de solicitação 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: |
falso |
Presença: |
Opcional |
Tipo: |
Booleanos |
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 isso é verdadeiro, o Edge considera os valores dos
seguintes cabeçalhos de resposta, comparando os valores com os definidos pelo
<ExpirySettings>
ao definir o time to live:
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: |
falso |
Presença: |
Opcional |
Tipo: |
Booleanos |
Observações sobre uso
O tamanho máximo de cada objeto armazenado em cache é de 256 KB. Para informações detalhadas sobre como o Edge de processos do Google Cloud, consulte Cache internos.
Com a configuração na política ResponseCache, é possível fazer com que o Edge inclua a resposta HTTP cabeçalhos na configuração da expiração de entrada e das 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 o Edge lida com cabeçalhos de resposta com a política ResponseCache, consulte Suporte para cabeçalhos de resposta HTTP.
Como configurar a expiração de entradas no cache
Assim como na política
de preenchimento de cache, é possível definir a expiração de uma entrada de cache de resposta (o time to live) usando o
elemento <ExpirySettings>
. Na política ResponseCache, também é possível usar o Edge
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 o Edge considere e compare os cabeçalhos de resposta com o conjunto de valores
por <ExpirySettings>
e, em seguida, use o valor mais baixo entre os dois. Quando
considerando os cabeçalhos de resposta, o Edge escolhe o valor disponível conforme descrito nas
seguinte:
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 finalidade geral, como a política Preencher cache, com
ResponseCache, você usa os elementos <CacheKey>
e <Scope>
para
configurar a criação da chave de cache para entradas de cache. 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
Edge para nuvem pública: o cache é criptografado apenas em PCI e compatíveis com a HIPAA organizações. A criptografia dessas organizações é configurada durante o provisionamento da organização.
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 as variáveis de fluxo, consulte a Referência de variáveis.
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 |
Booleanos | Somente leitura | Verdadeiro se a execução da política for bem-sucedida |
responsecache.{policy_name}.invalidentry |
Booleanos | 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 essa política.
Nome do erro | Causa | Corrigir |
---|---|---|
InvalidTimeout |
Se o
elemento <CacheLookupTimeoutInSeconds> da política ResponseCache estiver definido como um número negativo,
a implantação do proxy da API falhará. |
build |
InvalidCacheResourceReference |
Esse erro ocorre quando o elemento <CacheResource> em uma política ResponseCache está definido como um
nome que não existe no ambiente em que o proxy da 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 do 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.