Como trabalhar com chaves de cache

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

Confira a documentação da Apigee Edge.

Ao usar políticas de cache, você garante a exclusividade das chaves de valor armazenadas em cache configurando as chaves de cache. Uma chave de cache, junto com outros valores que podem ser configurados, oferece a você uma maneira confiável de extrair os mesmos dados que foram armazenados. Você usa chaves de cache com as políticas PopulateCache, LookupCache, InvalidateCache e ResponseCache.

A Apigee usa os valores dos elementos de configuração (<Scope>, <CacheKey>/<Prefix> e <CacheKey>/<KeyFragment>) para compor um valor chave de cache, que é um identificador associado ao valor no cache. A composição da chave de cache funciona da mesma forma com todas as políticas de cache.

Com os seguintes elementos de configuração da política de cache, é possível criar uma chave de cache:

Elemento de configuração de cache	Descrição
<Scope> ou <CacheKey> / <Prefix>	Use os elementos <Scope> ou <CacheKey> <Prefix> para configurar um prefixo a ser aplicado na chave de cache final. <Scope> enumera uma lista de valores predefinidos. O elemento <CacheKey> <Prefix> modifica <Scope> para um valor que você escolher.
<CacheKey>/<KeyFragment>	Use um ou mais elementos <KeyFragment> <CacheKey> combinados para especificar um identificador exclusivo para entradas de cache. Os valores de KeyFragment podem ser literais estáticos ou definidos com base em variáveis.

A Apigee compõe a chave de cache de duas partes, a parte de prefixo e a parte do fragmento composto, separadas por um sublinhado duplo.

PREFIX_PART__FRAGMENT_PART

A parte do prefixo é determinada pelo elemento <Scope> ou pelo elemento <CacheKey> <Prefix>, se estiver presente. A parte do fragmento é composta por cada um dos valores de cada elemento <KeyFragment>, unidos por sublinhados duplos.

Com a política de cache de resposta, é possível anexar essa chave de cache com valores do cabeçalho de aceitação de resposta.

Como usar a {CacheKey}

O elemento <CacheKey> configura como a Apigee criará um identificador exclusivo (uma chave) para cada entrada de cache criada. Quando a Apigee recupera o valor armazenado em cache, ela usa a chave de cache para localizar o valor correto. Na política ResponseCache, uma configuração define a chave para o armazenamento em cache e a recuperação. Nas políticas PopulateCache e LookupCache, cada política precisa ter elementos <CacheKey> idênticos para garantir que um valor recuperado do cache corresponda a um valor inserido nele.

O elemento <CacheKey> pode incluir um único elemento <Prefix> opcional, bem como um ou mais elementos <KeyFragment>. No ambiente de execução, a Apigee concatena os valores determinados de cada parte dos dois sublinhados entre eles para compor a chave de cache.

Por exemplo, a configuração a seguir cria um valor de myprefix__hello__world para uso na chave de cache:

<CacheKey>
    <Prefix>myprefix</Prefix>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

É possível configurar a Apigee para usar uma chave de cache composta dinamicamente referenciando a variável em um elemento <KeyFragment>, como mostrado aqui:

<KeyFragment ref="variable_name"/>

Por exemplo, para fazer com que o valor da chave de cache incorpore o Content-Type da mensagem de solicitação, faça o seguinte:

<KeyFragment ref="request.header.Content-Type"/>

Considere a seguinte configuração:

<CacheKey>
  <Prefix>system1</Prefix>
  <KeyFragment>apiAccessToken</KeyFragment>
  <KeyFragment ref="request.header.Content-Type" />
  <KeyFragment>bar</KeyFragment>
</CacheKey>

Se a variável request.header.Content-Type tiver o valor application/json, isso resultará em uma chave de cache de system1__apiAccessToken__application/json__bar.

É possível usar variáveis definidas pela plataforma ou personalizadas em um atributo ref.

Chaves de cache derivadas dos parâmetros de consulta

Ao usar variáveis como request.queryparam.<queryparam_name> e request.querystring, é possível configurar uma chave de cache para que a chave inclua partes da string de consulta de uma solicitação. Por exemplo, o URL a seguir usa dois parâmetros de consulta (param1 e param2) que podem ser usados na chave de cache:

http://myaccount.apigee.net/mydata?param1=value1&param2=value2

O elemento <CacheKey> pode incorporar esses valores com uma configuração como a seguinte:

<CacheKey>
    <KeyFragment ref="request.queryparam.param1" />
    <KeyFragment ref="request.queryparam.param2" />
<CacheKey>

No ambiente de execução, a chave de cache inclui os valores de parâmetro concatenados, como no exemplo a seguir:

prefix_part__value1__value2

Em vez de especificar vários parâmetros de consulta distintos, é possível usar a variável request.querystring, que insere toda a string de parâmetros literalmente como parte da chave de cache. Lembre-se de que esse método considera todos os parâmetros, mas se a ordem dos parâmetros variar de uma solicitação para a próxima, a chave será diferente. Em outras palavras, param1=value1&param2=value2 e param2=value2&param1=value1 não resultam no mesmo valor de chave de cache.

Como usar <Scope> e <Prefix>

Os elementos <Scope> e <CacheKey> / <Prefix> oferecem uma maneira de organizar valores em cache em um namespace. A Apigee anexa um valor derivado deles à chave de cache. A vantagem de usar um escopo ou prefixo na chave de cache é que é possível invalidar todos os valores que compartilham um único prefixo, com uma chamada para a política InvalidateCache.

O elemento <Scope> é usado por padrão. Trata-se de uma enumeração com valores que variam de amplo a restrito, com o mais restrito como padrão. Esse valor padrão será usado, a menos que você especifique outro valor ou um valor de elemento <Prefix>. É possível modificar o valor <Scope> usando um elemento <CacheKey> / <Prefix>. Portanto, especifique um valor personalizado para o namespace.

Por exemplo, o valor <Scope> "Global", o escopo mais amplo, representa o nome da organização e do ambiente. Por isso, se o proxy for implantado em uma organização chamada "mycompany" e um ambiente chamado "prod", o valor resultante anexado como prefixo é o seguinte:

mycompany__prod__[FRAGMENT_PART]

Conforme descrito na política LookupCache, o escopo pode ser configurado para aumentar a especificidade de Global para Exclusivo. Um escopo Exclusivo é o mais específico e, portanto, representa um risco mínimo de colisões de namespaces em um determinado cache. Cada entrada de cache com um escopo Exclusivo é prefixada no seguinte formato:

orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]

Veja alguns exemplos. Eles presumem que a 16a revisão do proxy chamada "weatherapi" seja implantada em uma organização chamada "minhaempresa" e um ambiente chamado "prod", que o nome proxyEndpoint seja "padrão" e que a política de cache é anexada a um fluxo no proxyEndpoint.

Configuração	Resultado
<Scope>Global</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__hello__world
<Scope>Exclusive</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__weatherapi__16__default__hello__world
<Scope>Exclusive</Scope> <CacheKey> <Prefix>system1</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	system1__hello__world