Como trabalhar com chaves de cache

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

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 o prefixo Preencher a política de cache, política LookupCache, política InvalidateCache e política de cache de resposta.

Os valores dos elementos de configuração, <CacheKey>/<KeyFragment>, <Scope> e <Prefix>, são concatenados para criar um identificador associado ao valor armazenado em cache. Use essa mesma configuração para recuperar o valor.

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
<CacheKey>/<KeyFragment> Use os elementos <CacheKey> e <KeyFragment> 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.
<Scope> ou <Prefix> Use os elementos <Scope> ou <Prefix> para outras chaves de cache de namespace. <Scope> enumera uma lista de valores predefinidos. O elemento <Prefix> modifica <Scope> para um valor de sua escolha.

Esses valores são concatenados da forma a seguir, com os valores <Scope> ou <Prefix> separados dos valores KeyFragment por sublinhados duplos. Vários valores de KeyFragment também são separados por sublinhados duplos.

scope | prefix__keyfragment[__keyfragment]

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

O elemento <CacheKey> configura como o Edge criará um identificador exclusivo (uma chave) para cada entrada de cache criada. Quando o Edge recupera o valor armazenado em cache, ele 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 vários elementos <KeyFragment>. No ambiente de execução, os valores especificados por elementos <KeyFragment> são concatenados com dois sublinhados entre eles para fazer parte da chave de cache.

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

<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

Também é possível usar valores de variável em uma chave de cache fazendo referência à variável em um elemento <KeyFragment>, como mostrado a seguir:

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

Na configuração a seguir, a variável request.header.Content-Type tem o valor application/json.

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

Isso resulta em uma chave de cache terminada em apiAccessToken__application/json__bar.

Para uma lista das variáveis que podem ser usadas, consulte Referência de variáveis.

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:

other_key_parts__value1__value2

Quando você usa variáveis para inserir valores de parâmetros, os valores são concatenados na ordem sugerida pela ordem do elemento <KeyFragment>. Além disso, o Edge usará somente os valores que você referenciar especificamente com elementos <KeyFragment>. Se as listas de parâmetros de consulta de solicitação variarem, as variações não serão consideradas na chave de cache.

Uma alternativa é 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.

Para uma lista das variáveis que podem ser usadas, consulte Referência de variáveis.

Como usar <Scope> e <Prefix>

Os elementos <Scope> e <Prefix> fornecem uma maneira de aumentar a chave com um prefixo de namespace. Os valores que eles representam são anexados como prefixo à sua chave de cache.

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 <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 seu proxy foi implantado em uma organização chamada "mycompany" e um ambiente chamado "prod", o valor resultante anexado como prefixo é o seguinte:

Configuração Resultado
<Scope>Global</Scope> mycompany__prod__

Se você estiver usando o escopo "Global" com a chave de cache definida acima, o resultado será o seguinte:

Configuração Resultado
<Scope>Global</Scope>
<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>
mycompany__prod__hello__world

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__proxy|TargetName__[serializedCacheKey]

Por exemplo, uma chave de cache criada com o uso do valor Exclusivo para <Scope> é semelhante ao seguinte:

apifactory__test__weatherapi__16__default__apiAccessToken