Política ResponseCache

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

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.

Exemplos

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 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 Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

false Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

verdadeiro 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 name da política.

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:

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 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 códigos "sucessos", 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:

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 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 a ser usado 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 <CacheKey> com o apiAccessToken <KeyFragment> e um escopo <Global>, cada entrada será armazenada como orgName__envName__apiAccessToken, seguida pelo valor serializado do token de acesso. Para um proxy de API implantado em um ambiente chamado "test" em uma organização chamada "apifactory", os tokens de acesso são armazenados na seguinte chave de cache: apifactory__test__apiAccessToken.

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:

  • Se a política estiver anexada ao fluxo ProxyEndpoint, o prefixo estará no formato ApiProxyName_ProxyEndpointName.
  • Se a política estiver anexada a TargetEndpoint, o prefixo será do formato ApiProxyName_TargetName.

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.

A borda 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 isso for verdadeiro, o Edge considerará os valores dos cabeçalhos de resposta a seguir, comparando os valores com aqueles definidos por <ExpirySettings> ao definir a vida útil:

  • 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 o Edge processa o cache, consulte Internos do cache.

Com a configuração na política ResponseCache, é possível fazer com que o Edge inclua cabeçalhos de resposta HTTP na configuração da expiração da entrada de cache 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 processa 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 fazer com que 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 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, o Edge 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 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 organizações com PCI e HIPAA. 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 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 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á.
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.
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.
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.
InvalidMessagePatternForErrorCode Esse erro ocorre quando o elemento <SkipCacheLookup> ou <SkipCachePopulation> em uma política ResponseCache tem uma condição inválida.
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.

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.