Política PopulateCache

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

Confira a documentação da Apigee Edge.

Configura como os valores armazenados em cache precisam ser gravados no ambiente de execução.

A política de preenchimento de cache foi criada para gravar entradas em um cache de uso geral de curto prazo. Ele é usado em conjunto com a política de pesquisa de cache, para ler entradas de cache, e a política de invalidação de cache, para invalidar entradas.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Para armazenar em cache as respostas de recursos de back-end, consulte a Política de cache de resposta.

Referência de elemento

Veja a seguir os elementos que podem ser configurados nessa 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 a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir 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 será aplicada mesmo se ela permanecer anexada a um fluxo.	verdadeiro	Opcional
async	Esse atributo está obsoleto.	falso	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <CacheKey>

Configura um ponteiro exclusivo para um conjunto de dados armazenados no cache.

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

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	N/A

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

No ambiente de execução, os valores <KeyFragment> são prefixados com o valor do elemento <Scope> ou <Prefix>. Por exemplo, o seguinte resultado gera uma chave de cache de UserToken__apiAccessToken__<value_of_client_id>:

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

Use o elemento <CacheKey> em conjunto com <Prefix> e <Scope>. Para mais informações, consulte Como trabalhar com chaves de cache.

Elemento <CacheResource>

Especifica o cache em que as mensagens precisam ser armazenadas.

Omita esse elemento completamente se esta política, e suas políticas correspondentes de LookupCache e InvalidateCache, estiverem usando o cache compartilhado incluído.

<CacheResource>cache_to_use</CacheResource>

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

Para mais informações sobre como configurar caches, consulte Armazenamento de cache de uso geral.

Elemento <CacheKey>/<KeyFragment>

Especifica um valor que precisa ser incluído na chave de cache. Especifique uma variável para remover a referência com o atributo ref ou um valor fixo.

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

Padrão:	N/A
Presença:	zero ou mais
Tipo:	N/A

No ambiente de execução, a Apigee cria a chave de cache adicionando o valor recebido do elemento <Scope> ou <Prefix> a uma concatenação dos valores resolvidos de cada um dos elementos <KeyFragment>. Para mais informações, consulte Como trabalhar com chaves de cache.

Atributos

Atributo	Tipo	Padrão	Obrigatório	Descrição
ref	string		Não	A variável da qual conseguir o valor. Não pode ser usado se esse elemento contiver um valor literal.

Elemento <CacheKey>/<Prefix>

Especifica um valor fixo para usar como prefixo da chave de cache.

<Prefix>prefix_string</Prefix>

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

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

No ambiente de execução, a Apigee cria a chave de cache adicionando o valor recebido do elemento <Scope> ou <Prefix> a uma concatenação dos valores resolvidos de cada um dos elementos <KeyFragment>. Para mais informações, consulte Como trabalhar com chaves de cache.

Elemento <ExpirySettings>

Especifica quando uma entrada de cache expira.

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	N/A

Elementos filhos de <ExpirySettings>

Use exatamente um elemento filho. A tabela a seguir descreve os elementos filhos de <ExpirySettings>:

Elemento filho	Descrição
<TimeoutInSeconds>	O número de segundos após o qual uma entrada de cache expira. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Esse elemento substitui o elemento TimeoutInSec, que foi descontinuado.
<ExpiryDate>	Especifica a data em que uma entrada de cache expira. Especifique uma string no formato mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Se a data especificada estiver no passado, a política aplicará o time to live máximo à entrada armazenada em cache. O máximo é de 30 dias.
<TimeOfDay>	Especifica o horário em que uma entrada de cache deve expirar. Especifique uma string no formato HH:mm:ss, em que HH representa a hora em um relógio de 24 horas, no fuso horário UTC. Por exemplo, 14:30:00 significa 2:30 da tarde. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Observações: Especifique os horários pelo fuso horário universal coordenado (UTC, na sigla em inglês). Preencher a notação de tempo do cache segue a notação de data padrão internacional definida no padrão internacional ISO 8601.

Especifique apenas um dos possíveis elementos filhos. Se você especificar vários elementos, a ordem de precedência será: TimeoutInSeconds, ExpiryDate, TimeOfDay.

Com cada um dos elementos filhos de <ExpirySettings> acima, se você especificar o atributo ref opcional no elemento filho, a política recuperará o valor de expiração da variável de contexto nomeada. Se a variável não for definida, a política usará 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>

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

A configuração <Scope> determina uma chave de cache que é anexada de acordo com o valor <Scope>. Por exemplo, uma chave de cache assume o seguinte formato quando o escopo é definido como Exclusive:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ ]

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

Use o elemento <Scope> em conjunto com <CacheKey> e <Prefix>. Para mais informações, consulte Como trabalhar com chaves de cache.

Valores aceitáveis

Global	A chave de cache é compartilhada entre todos os proxies de API implantados no ambiente. A chave de cache é precedida no formato orgName __ orgName __. Se você definir uma entrada <CacheKey> com o apiAccessToken <KeyFragment> e um escopo <Global>, cada entrada será armazenada como orgName__envName__apiAccessToken, seguida pelo valor serializado do token de acesso. Para um proxy de API implantado em um ambiente chamado "test" em uma organização chamada "apifactory", os tokens de acesso são armazenados na seguinte chave de cache: apifactory__test__apiAccessToken.
Application	Nome do proxy da API é usado como prefixo. A chave de cache tem o formato orgName__envName__apiProxyName.
Proxy	A configuração do ProxyEndpoint é usada como prefixo. A chave de cache é precedida no formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .
Target	A configuração TargetEndpoint é usada como prefixo. Chave do cache com o formato orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .
Exclusive	Padrão. Este é o mais específico e, portanto, apresenta o risco mínimo de colisões de namespaces em um determinado cache. O prefixo estará em um destes dois formatos: Se a política estiver anexada ao fluxo ProxyEndpoint, o prefixo estará no formato ApiProxyName_ProxyEndpointName. Se a política estiver anexada a TargetEndpoint, o prefixo será do formato ApiProxyName_TargetName. Chave de cache no formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName Por exemplo, a string completa pode ter esta aparência: apifactory__test__weatherapi__16__default__apiAccessToken .

Elemento <Source>

Especifica a variável com o valor que precisa ser gravado no cache.

<Source>source_variable</Source>

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Observações:

• Os objetos JSON são armazenados exclusivamente no cache em memória (L1).
• Se você pretende armazenar esses objetos no cache persistente (L2), recomendamos serializá-los para um formato de string.
• Ao seguir essa prática, você consegue utilizar efetivamente o cache L2 e maximizar a eficiência do armazenamento em cache.
• Para mais informações, consulte Caches internos.
  

Observações sobre uso

Use esta política para armazenamento em cache de uso geral. No ambiente de execução, a política <PopulateCache> grava dados da variável especificada no elemento <Source> no cache especificado no elemento <CacheResource>. É possível usar os elementos <CacheKey>, <Scope> e <Prefix> para especificar uma chave que pode ser usada da política <LookupCache> para recuperar o valor. Use o elemento <ExpirySettings> para configurar quando o valor em cache deve expirar.

O armazenamento em cache para uso geral com as políticas PopulateCache, LookupCache e InvalidateCache usa um cache configurado por você ou um compartilhado que, por padrão, já vem incluído. Na maioria dos casos, o cache compartilhado subjacente precisa atender às suas necessidades. Para usar esse cache, basta omitir o elemento <CacheResource>.

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

Para saber mais sobre o armazenamento de dados subjacente, consulte a página de detalhes sobre cache.

Sobre a criptografia de cache

Apigee e Apigee híbrida (versão 1.4 e posterior): os dados de cache e KVM são sempre criptografados.

Códigos de erro

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP Status	Occurs when
policies.populatecache.EntryCannotBeCached	500	An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidCacheResourceReference	This error occurs if the <CacheResource> element in the PopulateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFound	The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	populatecache.POP-CACHE-1.failed = true

Example error response

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

Example fault rule

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