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:

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>

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>

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

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>

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

Elemento <CacheKey>/<Prefix>

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

<Prefix>prefix_string</Prefix>

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>

Elementos filhos de <ExpirySettings>

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

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

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>

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__ [ serializedCacheKey ]

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

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>

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

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.

Erros de implantação

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

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.

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>