Política ResponseCache

Esta é a documentação do Apigee Edge.
Acesse 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).

Amostras

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

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

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:

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>

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>

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

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>

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>

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

Elemento <CacheKey>/<Prefix>

Especifica um valor para usar como prefixo da chave de cache.

<Prefix>prefix_string</Prefix>

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>

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>

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>

Atributos

<ExpiryDate ref="" />

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>

Atributos

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.

Atributos

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>

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

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>

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>

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>

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>

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.

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.

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.