Política PopulateCache

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

Veja a documentação do Apigee Edge.

A política PopulateCache 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 o artigo 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 o artigo 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 da cache deve expirar. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Este elemento substitui o elemento TimeoutInSec agora 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 anteposta 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 tem o prefixo 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 de cache anteposta no formulário orgName__envName__apiProxyName__targetEndpointName .
Exclusive	Predefinição. Esta é a mais específica e, por conseguinte, 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 posterior): os dados da cache e do KVM são sempre encriptados.

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>