Política LookupCache

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

Veja a documentação do Apigee Edge.

Configura a forma como os valores em cache devem ser obtidos no tempo de execução.

Esta política destina-se a utilização em armazenamento em cache a curto prazo de fins gerais. É usado em conjunto com a política PopulateCache (para escrever entradas) e a política InvalidateCache (para invalidar entradas).

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Para colocar em cache as respostas dos recursos de back-end, consulte a política ResponseCache.

Referência do elemento

A lista seguinte indica os elementos que pode configurar nesta política.

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

Uma cache partilhada está incluída por predefinição. Para usar a cache partilhada, omita o elemento <CacheResource> nesta configuração da política.

Para saber mais sobre o armazenamento de dados subjacente, consulte o artigo Funcionamento interno da cache. Para mais informações sobre a configuração de caches, consulte o artigo Criação de cache de uso geral.

Atributos <LookupCache>

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <AssignTo>

Especifica a variável à qual a entrada da cache é atribuída depois de ter sido obtida da cache. A variável tem de ser gravável. Se a pesquisa na cache não obtiver um valor, a variável não é definida.

<AssignTo>variable_to_receive_cached_value</AssignTo>

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	String

Elemento <CacheKey>

Configura um ponteiro único para um fragmento de dados armazenado na cache.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	N/A

<CacheKey> cria o nome de cada parte dos dados armazenados na cache.

Em tempo de execução, os valores <KeyFragment> são precedidos pelo valor do elemento <Scope> ou pelo valor <Prefix>. Por exemplo, o seguinte resulta numa chave da cache de UserToken__apiAccessToken__<value_of_client_id>:

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

Usa o elemento <CacheKey> em conjunto com <Prefix> e <Scope>. Para mais informações, consulte o artigo Trabalhar com chaves de cache.

Elemento <CacheLookupTimeoutInSeconds>

Especifica o número de segundos após o qual uma pesquisa de cache sem êxito é considerada uma falha de cache. Se isto ocorrer, o fluxo é retomado ao longo do caminho de falha de cache.

<CacheLookupTimeoutInSeconds>12</CacheLookupTimeoutInSeconds>

Predefinição:	12
Presença:	Opcional
Tipo:	Número inteiro

Elemento <CacheResource>

Especifica a cache onde as mensagens devem ser armazenadas.

Omita este elemento completamente se esta política (e as políticas PopulateCache e InvalidateCache correspondentes) estiver a usar a cache partilhada incluída.

<CacheResource>cache_to_use</CacheResource>

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

Para mais informações sobre a configuração de caches, consulte o artigo Caches de uso geral.

Elemento <CacheKey>/<KeyFragment>

Especifica um valor que deve ser incluído na chave da cache. Especifique uma variável a desreferenciar com o atributo ref ou um valor fixo.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Predefinição:	N/A
Presença:	Opcional
Tipo:	N/A

Em tempo de execução, o Apigee cria a chave da cache antepondo o valor obtido do elemento <Scope> ou do elemento <Prefix> a uma concatenação dos valores resolvidos de cada um dos elementos <KeyFragment>. Para mais informações, consulte Trabalhar com chaves de cache.

Atributos

Atributo	Tipo	Predefinição	Obrigatória	Descrição
ref	de string		Não	A variável a partir da qual obter o valor. Não deve ser usado se este elemento contiver um valor literal.

Elemento <CacheKey>/<Prefix>

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

<Prefix>prefix_string</Prefix>

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

Um elemento <Prefix> substitui qualquer elemento <Scope>.

Em tempo de execução, o Apigee cria a chave da cache antepondo o valor obtido do elemento <Scope> ou do elemento <Prefix> a uma concatenação dos valores resolvidos de cada um dos elementos <KeyFragment>. Para mais informações, consulte Trabalhar com chaves de cache.

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>

Predefinição:	"Exclusivo"
Presença:	Opcional
Tipo:	String

A definição <Scope> determina uma chave de cache que é adicionada de acordo com o valor <Scope>. Por exemplo, uma chave de cache teria o seguinte formato quando o âmbito é definido como Exclusive: orgName__envName__applicationName__proxy|TargetName__ [ serializedCacheKey ].

Se um elemento <Prefix> estiver presente em <CacheKey>, substitui o valor do elemento <Scope>. Os valores válidos incluem as enumerações abaixo.

Para mais informações, consulte o artigo Trabalhar com chaves de cache.

Valores aceitáveis

Global	A chave da cache é partilhada por todos os proxies de API implementados no ambiente. A chave da cache é adicionada no início no formato orgName __ envName __. Se definir uma entrada <CacheKey> com o <KeyFragment> apiAccessToken e um âmbito <Global>, cada entrada é armazenada como orgName__envName__apiAccessToken, seguida do valor serializado do token de acesso. Para um proxy de API implementado num ambiente denominado "test" numa organização denominada "apifactory", os tokens de acesso seriam armazenados na seguinte chave de cache: apifactory__test__apiAccessToken.
Application	O nome do proxy da API é usado como prefixo. A chave da cache é adicionada no formulário orgName__envName__applicationName.
Proxy	A configuração ProxyEndpoint é usada como prefixo. A chave da cache é adicionada sob a forma orgName__envName__applicationName__proxyEndpointName .
Target	A configuração TargetEndpoint é usada como prefixo. Chave da cache anteposta no formulário orgName__envName__applicationName__targetEndpointName .
Exclusive	Predefinição. Esta é a mais específica e, por isso, apresenta um risco mínimo de colisões de espaço de nomes numa determinada cache. O prefixo tem um de dois formatos: Se a política estiver anexada ao fluxo ProxyEndpoint, o prefixo tem o formato ApiProxyName_ProxyEndpointName. Se a política estiver anexada em TargetEndpoint, o prefixo tem o formato ApiProxyName_TargetName. Chave de cache anteposta no formulário orgName__envName__applicationName__proxyNameITargetName Por exemplo, a string completa pode ter o seguinte aspeto: apifactory__test__weatherapi__default__apiAccessToken .

Notas de utilização

Use esta política para o armazenamento em cache de uso geral. Em tempo de execução, a política LookupCache obtém um valor da cache, atribuindo o valor à variável especificada com o elemento AssignTo (se não for obtido nenhum valor, a variável não é definida). Procura o valor com base numa chave de cache criada através da configuração que combina os elementos CacheKey e Scope. Por outras palavras, para obter um valor específico adicionado à cache por uma política PopulateCache, a sua política LookupCache tem de ter elementos relacionados com a chave da cache configurados da mesma forma que a política PopulateCache.

O armazenamento em cache de uso geral com a política PopulateCache, política LookupCache e política InvalidateCache usa uma cache que configura ou uma cache partilhada incluída por predefinição. Na maioria dos casos, a cache partilhada subjacente deve satisfazer as suas necessidades. Para usar a cache predefinida, basta omitir o elemento <CacheResource>.

Para mais informações sobre a configuração de caches, consulte o artigo Caches de uso geral. Para saber mais sobre o armazenamento de dados subjacente, consulte o artigo Funcionamento interno da cache.

Variáveis de fluxo

As variáveis de fluxo podem ser usadas para configurar o comportamento dinâmico de tempo de execução para políticas e fluxos, com base nos cabeçalhos HTTP ou no conteúdo das mensagens, ou no contexto disponível no fluxo. Para mais informações acerca das variáveis de fluxo, consulte a referência de variáveis de fluxo.

As seguintes variáveis de fluxo predefinidas estão disponíveis depois de personalizar o comportamento da cache que define numa política LookupCache.

Variáveis	Tipo	Autorização	Descrição
lookupcache.{policy-name}.cachename	String	Só de leitura	Devolve o nome da cache usado na política.
lookupcache.{policy-name}.cachekey	String	Só de leitura	Devolve a chave usada.
lookupcache.{policy-name}.cachehit	Booleano	Só de leitura	Verdadeiro se a política tiver encontrado um valor para a chave da cache especificada.
lookupcache.{policy-name}.assignto	String	Só de leitura	Devolve a variável à qual a cache está atribuída.

Códigos de erro

Esta secção descreve as mensagens de erro e as variáveis de fluxo que são definidas quando esta política aciona um erro. Estas informações são importantes se estiver a desenvolver regras de falhas para um proxy. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Prefixo do código de erro

N/A

Erros de tempo de execução

Esta política não gera erros de tempo de execução.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Nome do erro	Causa	Corrigir
InvalidCacheResourceReference	Este erro ocorre se o elemento <CacheResource> estiver definido para um nome que não existe no ambiente onde o proxy de API está a ser implementado.
InvalidTimeout	Se o elemento <CacheLookupTimeoutInSeconds> estiver definido como um número negativo, a implementação do proxy de API falha.
CacheNotFound	Este erro ocorre se a cache específica mencionada na mensagem de erro não tiver sido criada num componente do processador de mensagens específico.

Variáveis de falha

N/A

Exemplo de resposta de erro

N/A