Política ResponseCache

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ícone da política

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 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. Consulte também:

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.

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

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

Diagrama que mostra o que acontece quando você define UseResponseCacheHeaders como verdadeiro.

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