Política PopulateCache

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 escritos no tempo de execução.

A política Populate Cache foi concebida para escrever entradas numa cache de uso geral a curto prazo. É usada em conjunto com a política de cache de pesquisa (para ler entradas de cache) e a política de cache de invalidação (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 de Cache de Respostas.

Referência do elemento

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

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

Atributos <PopulateCache>

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

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

As chaves da cache estão limitadas a um tamanho de 2 KB.

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

Especifica a cache onde as mensagens devem ser armazenadas.

Omita este elemento completamente se esta política (e as políticas LookupCache 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:	zero ou mais
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 fixo 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 <ExpirySettings>

Especifica quando uma entrada de cache deve expirar.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

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

Elementos secundários de <ExpirySettings>

Use exatamente um elemento filho. A tabela seguinte fornece uma descrição dos elementos subordinados de <ExpirySettings>:

Elemento secundário	Descrição
<TimeoutInSeconds>	O número de segundos após os quais uma entrada de cache deve expirar. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Este elemento substitui o elemento TimeoutInSec, que foi descontinuado.
<ExpiryDate>	Especifica a data em que uma entrada da cache deve expirar. Especifique uma string no formato mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Se a data especificada for no passado, a política aplica o tempo de vida máximo à entrada em cache. Este máximo é de 30 dias.
<TimeOfDay>	Especifica a hora do dia em que uma entrada da cache deve expirar. Especifique uma string no formato HH:mm:ss, em que HH representa a hora num relógio de 24 horas, no fuso horário UTC. Por exemplo, 14:30:00 implica 2:30 da tarde. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Notas: Especifique as horas no fuso horário Tempo Universal Coordenado (UTC). A notação de tempo de preenchimento da cache segue a notação de data da norma internacional definida na norma internacional ISO 8601.

Deve especificar apenas um dos elementos secundários possíveis. Se especificar vários elementos, a ordem de precedência é:TimeoutInSeconds, ExpiryDate, TimeOfDay.

Com cada um dos elementos secundários acima de <ExpirySettings>, se especificar o atributo ref opcional no elemento secundário, a política vai obter o valor de validade da variável de contexto com nome. Se a variável não estiver definida, a política usa o valor de texto literal do elemento filho.

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

Usa o elemento <Scope> em conjunto com <CacheKey> e <Prefix>. 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__apiProxyName.
Proxy	A configuração ProxyEndpoint é usada como prefixo. A chave da cache é adicionada sob a forma orgName__envName__apiProxyName__proxyEndpointName .
Target	A configuração TargetEndpoint é usada como prefixo. Chave da cache anteposta no formulário orgName__envName__apiProxyName__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 da cache anteposta no formulário orgName__envName__apiProxyName__proxyNameITargetName Por exemplo, a string completa pode ter o seguinte aspeto: apifactory__test__weatherapi__default__apiAccessToken .

Elemento <Source>

Especifica a variável cujo valor deve ser escrito na cache.

<Source>source_variable</Source>

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

Notas:

• Os objetos JSON são armazenados exclusivamente na cache na memória (L1).
• Se pretender colocar estes objetos em cache na cache persistente (L2), recomendamos que os serialize num formato de string.
• Seguindo esta prática, pode usar eficazmente a cache de nível 2 e maximizar a eficiência do armazenamento em cache.
• Para mais informações, consulte o artigo Funcionamento interno da cache.
  

Notas de utilização

Use esta política para o armazenamento em cache de fins gerais. Em tempo de execução, a política <PopulateCache> escreve dados da variável especificada no elemento <Source> na cache especificada no elemento <CacheResource>. Pode usar os elementos <CacheKey>, <Scope> e <Prefix> para especificar uma chave que pode usar a partir da política <LookupCache> para obter o valor. Use o elemento <ExpirySettings> para configurar quando o valor em cache deve expirar.

O armazenamento em cache de uso geral com a política PopulateCache, LookupCache policy e InvalidateCache policy 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 esta cache, basta omitir o elemento <CacheResource>.

Limites da cache: aplicam-se vários limites da cache, como o tamanho do nome e do valor, o número total de caches, o número de itens numa cache e a expiração.

Para saber mais sobre o armazenamento de dados subjacente, consulte o artigo Funcionamento interno da cache.

Acerca da encriptação da cache

Apigee e Apigee híbrido (versão 1.4 e posteriores): os dados da cache e da KVM são sempre encriptados.

Códigos de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha	Status do HTTP	Ocorre quando
policies.populatecache.EntryCannotBeCached	500	Uma entrada não pode ser armazenada em cache. O objeto de mensagem em cache não é uma instância de uma classe que é serializável.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Corrigir" para informações detalhadas sobre a solução de problemas.

Nome do erro	Causa	Correção
InvalidCacheResourceReference	Esse erro ocorrerá se o elemento <CacheResource> na política PopulateCache for definido como um nome que não existe no ambiente em que o proxy de API está sendo implantado.
CacheNotFound	O cache especificado no elemento <CacheResource> não existe.

Variáveis de falha

Essas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name é o nome especificado pelo usuário da política que causou a falha.	populatecache.POP-CACHE-1.failed = true

Exemplo de resposta de erro

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Exemplo de regra de falha

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>