Trabalhar com chaves de cache

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Quando usa políticas de cache, garante a exclusividade das chaves de valores em cache através da configuração de chaves de cache. Uma chave de cache, juntamente com outros valores que pode configurar, oferece-lhe uma forma fiável de obter os mesmos dados que introduziu. Usa chaves de cache com a política PopulateCache, política LookupCache, política InvalidateCache e política ResponseCache.

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

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

Elemento de configuração da cache	Descrição
<Scope> ou <CacheKey> / <Prefix>	Use o elemento <Scope> ou o elemento <CacheKey> <Prefix> para configurar um prefixo a aplicar à chave de cache final. <Scope> enumera uma lista de valores predefinidos. O elemento <CacheKey> <Prefix> substitui <Scope> por um valor fixo à sua escolha.
<CacheKey>/<KeyFragment>	Use um ou mais elementos <CacheKey> <KeyFragment> combinados para especificar um identificador único para as entradas da cache. Os valores de KeyFragment podem ser literais estáticos ou definidos a partir de variáveis.

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

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 dois sublinhados.

Com a política de cache de respostas, pode anexar opcionalmente esta chave de cache com valores do cabeçalho Accept da resposta.

Usar <CacheKey>

O elemento <CacheKey> configura a forma como o Apigee cria um identificador exclusivo (uma chave) para cada entrada de cache que cria. Quando o Apigee obtém o valor em cache, 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 obtenção. Nas políticas PopulateCache e LookupCache, cada política tem de ter elementos <CacheKey>idênticos para garantir que um valor obtido da cache corresponde a um valor aí colocado.

O elemento <CacheKey> pode incluir um único elemento <Prefix> opcional, bem como um ou mais elementos <KeyFragment>. Em tempo de execução, o Apigee concatena os valores determinados de cada parte com dois carateres de sublinhado entre eles para formar a chave de cache.

Por exemplo, a seguinte configuração cria um valor de myprefix__hello__world para utilização na chave da cache:

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

Pode configurar o Apigee para usar uma chave de cache composta dinamicamente ao referenciar a variável num elemento <KeyFragment>, conforme mostrado aqui:

<KeyFragment ref="variable_name"/>

Por exemplo, para que o valor da chave de cache incorpore o Content-Type da mensagem de pedido, 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, isto resulta numa chave da cache de system1__apiAccessToken__application/json__bar.

Pode usar variáveis definidas pela plataforma ou personalizadas num atributo ref.

Chaves de cache derivadas de parâmetros de consulta

Ao usar variáveis como request.queryparam.<queryparam_name> e request.querystring, pode configurar uma chave de cache para que a chave inclua partes da string de consulta de um pedido. Por exemplo, o seguinte URL usa dois parâmetros de consulta, param1 e param2, que pode usar na sua chave de cache:

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

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

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

Em tempo de execução, a chave da cache incluiria os valores dos parâmetros concatenados, como no seguinte exemplo:

prefix_part__value1__value2

Em vez de especificar vários parâmetros de consulta distintos, pode usar a variável request.querystring, que insere literalmente toda a string de parâmetros como parte da chave da cache. Tenha em atenção que, embora este método tenha em conta todos os parâmetros, se a ordem dos parâmetros variar de um pedido para o seguinte, a chave será diferente. Por outras palavras, param1=value1&param2=value2 e param2=value2&param1=value1 não resultam no mesmo valor da chave da cache.

Usar <Scope> e <Prefix>

Os elementos <Scope> e <CacheKey> fornecem uma forma de organizar os valores em cache num espaço de nomes.<Prefix> O Apigee antepõe um valor derivado dos mesmos à chave da cache. A vantagem de usar um âmbito ou um prefixo na chave da cache é que pode invalidar todos os valores que partilham um único prefixo com uma chamada para a política InvalidateCache.

O elemento <Scope> é usado por predefinição. É uma enumeração cujos valores variam de amplos a restritos, sendo o mais restrito o valor predefinido. Este valor predefinido é usado, a menos que especifique outro valor ou especifique um valor do elemento <Prefix>. Pode substituir o valor <Scope> através de um elemento <CacheKey>/<Prefix> e, assim, especificar um valor personalizado para o espaço de nomes.

Por exemplo, o valor <Scope> "Global" (o âmbito mais amplo) representa o nome da organização e do ambiente. Assim, se o seu proxy for implementado numa organização denominada "mycompany" e num ambiente denominado "prod", o valor anteposto resultante será o seguinte:

mycompany__prod__[FRAGMENT_PART]

Conforme descrito na política LookupCache, o âmbito pode ser configurado para aumentar a especificidade de Global para Exclusivo. Um âmbito exclusivo é o mais específico e, por isso, representa um risco mínimo de colisões de espaço de nomes numa determinada cache. Cada entrada da cache com um âmbito exclusivo tem o seguinte prefixo:

orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]

Seguem-se alguns exemplos. Estes exemplos pressupõem que a 16.ª revisão do seu proxy denominado "weatherapi" está implementada numa organização denominada "mycompany" e num ambiente denominado "prod", e que o nome proxyEndpoint é "default" e que a política de cache está 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 Neste caso, o elemento <Prefix> substitui <Scope>, motivo pelo qual o espaço de nomes system1 aparece no resultado.