Você está vendo a documentação do Apigee Edge.
Acesse a
documentação da Apigee X. informações
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.
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 Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
false | Opcional |
enabled |
Defina como Defina como |
verdadeiro | Opcional |
async |
Esse atributo está obsoleto. |
false | 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 |
---|---|
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 Como criar e editar um cache de ambiente.
Elemento <CacheKey>/<KeyFragment>
Especifica um valor que deve ser incluído na chave de cache, criando um namespace para as solicitações correspondentes às respostas em cache.
<KeyFragment ref="variable_name"/> <KeyFragment>literal_string</KeyFragment>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
N/A |
Pode ser uma chave (um nome estático fornecido) ou um valor (uma entrada dinâmica definida por uma referência a uma variável). Todos os fragmentos especificados combinados (além do prefixo) são concatenados para criar a chave de cache.
<KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" />
Use o elemento <KeyFragment>
em conjunto com
<Prefix>
e <Scope>
. 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 para usar como prefixo da chave de cache.
<Prefix>prefix_string</Prefix>
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: |
String |
Use esse valor em vez de <Scope>
quando quiser especificar seu próprio valor em vez de um valor enumerado com <Scope>
. Se definido, <Prefix>
precede o valor da chave de cache das entradas gravadas no cache. Um valor de elemento <Prefix>
modifica um valor de elemento <Scope>
.
Use o elemento <Prefix>
em conjunto com
<CacheKey>
e <Scope>
. Para mais informações, consulte Como trabalhar com chaves de cache.
Elemento <ExpirySettings>
Especifica quando uma entrada de cache expira. Quando
presente, <TimeoutInSeconds>
substitui
<TimeOfDay>
e <ExpiryDate>
.
<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 |
<ExpiryDate> |
Especifica a data em que uma entrada de cache expira. Especifique uma string no formato <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 <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 opcional ref
no elemento filho, a política vai
recuperar o valor de validade da variável de contexto nomeada. Se a variável não for definida,
a política vai 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__ [ 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
Global |
A chave de cache é compartilhada entre todos os proxies de API implantados no ambiente. A chave de cache é precedida no formato orgName __ envName __. Se você definir uma entrada |
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:
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 sobre o 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 de uso geral com as políticas PopulateCache, LookupCache e InvalidateCache usa
um cache configurado por você ou um cache compartilhado incluído por padrão. 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. Para mais informações sobre como configurar caches, consulte Como criar e editar um cache de ambiente.
Sobre a criptografia de cache
Edge para nuvem pública: o cache é criptografado apenas em organizações com PCI e HIPAA. A criptografia dessas organizações é configurada durante o provisionamento da organização.
Códigos de erro
Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta 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 essa política.
Erro de nome | Causa | Corrigir |
---|---|---|
InvalidCacheResourceReference |
Esse erro ocorrerá se o elemento <CacheResource> na política PopulateCache estiver definido como um nome que não exista no ambiente em que o proxy de API está sendo implantado. |
build |
CacheNotFound |
O cache especificado no elemento <CacheResource> não existe. |
build |
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>