Norme di PopulateCache

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Configura la modalità di scrittura dei valori memorizzati nella cache in fase di runtime.

Il criterio Popola cache è progettato per scrivere voci in una cache generica a breve termine. Viene utilizzato insieme al criterio Cache di ricerca (per la lettura delle voci della cache) e al criterio Annulla convalida della cache (per l'annullamento della convalida delle voci).

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Per memorizzare nella cache le risposte delle risorse di backend, consulta le norme sulla cache delle risposte.

Riferimento elemento

Di seguito sono elencati gli elementi che puoi configurare in questo criterio.

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

Attributi <PopulateCache>

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo	Descrizione	Predefinito	Presence
name	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Predefinito	N/D Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence	Facoltativo
Tipo	Stringa

Elemento <CacheKey>

Configura un puntatore univoco a un insieme di dati memorizzati nella cache.

Le chiavi della cache sono limitate a una dimensione di 2 kB.

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

Predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	N/D

<CacheKey> crea il nome di ogni dato memorizzato nella cache.

In fase di runtime, i valori di <KeyFragment> vengono anteposti al valore dell'elemento <Scope> o al valore di <Prefix>. Ad esempio, i seguenti generano una chiave della cache di UserToken__apiAccessToken__<value_of_client_id>:

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

Utilizzi l'elemento <CacheKey> in combinazione con <Prefix> e <Scope>. Per saperne di più, consulta Utilizzo delle chiavi della cache.

Elemento <CacheResource>

Specifica la cache in cui devono essere archiviati i messaggi.

Ometti completamente questo elemento se questa norma (e le norme corrispondenti LookupCache e InvalidateCache) utilizza la cache condivisa inclusa.

<CacheResource>cache_to_use</CacheResource>

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

Per saperne di più sulla configurazione delle cache, consulta la sezione Memorizzazione nella cache per uso generico.

Elemento <CacheKey>/<KeyFragment>

Specifica un valore da includere nella chiave cache. Specifica una variabile a cui fare dereferenziazione con l'attributo ref o un valore fisso.

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

Predefinito:	N/D
Presenza:	zero o più
Tipo:	N/D

In fase di runtime, Apigee crea la chiave della cache anteponendo il valore ottenuto dall'elemento <Scope> o dall'elemento <Prefix> a una concatenazione dei valori risolti di ciascuno degli elementi <KeyFragment>. Per saperne di più, consulta Utilizzo delle chiavi della cache.

Attributi

Attributo	Tipo	Predefinito	Obbligatorio	Descrizione
ref	string		No	La variabile da cui ottenere il valore. Non deve essere utilizzato se questo elemento contiene un valore letterale.

Elemento <CacheKey>/<Prefix>

Specifica un valore fisso da utilizzare come prefisso della chiave cache.

<Prefix>prefix_string</Prefix>

Predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

Un elemento <Prefix> sostituisce qualsiasi elemento <Scope>.

In fase di runtime, Apigee crea la chiave della cache anteponendo il valore ottenuto dall'elemento <Scope> o dall'elemento <Prefix> a una concatenazione dei valori risolti di ciascuno degli elementi <KeyFragment>. Per saperne di più, consulta Utilizzo delle chiavi della cache.

Elemento <ExpirySettings>

Specifica la scadenza di una voce della cache.

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

Predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	N/D

Elementi secondari di <ExpirySettings>

Utilizza esattamente un elemento secondario. La tabella seguente fornisce una descrizione degli elementi secondari di <ExpirySettings>:

Elemento secondario	Descrizione
<TimeoutInSeconds>	Il numero di secondi dopo i quali una voce della cache deve scadere. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Questo elemento sostituisce l'elemento TimeoutInSec ora deprecato.
<ExpiryDate>	Specifica la data di scadenza di una voce della cache. Specifica una stringa nel modulo mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Se la data specificata è nel passato, il criterio applicherà il time-to-live massimo alla voce memorizzata nella cache. Il periodo massimo è di 30 giorni.
<TimeOfDay>	Specifica l'ora del giorno in cui una voce della cache deve scadere. Specifica una stringa nel formato HH:mm:ss, dove HH rappresenta l'ora su un orologio di 24 ore, nel fuso orario UTC. Ad esempio, 14:30:00 indica le 14:30. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Note: Specifica gli orari nel fuso orario UTC (Coordinated Universal Time). La notazione dell'ora della cache segue la notazione internazionale della data definita nello standard internazionale ISO 8601.

Devi specificare solo uno dei possibili elementi secondari. Se specifichi più elementi, l'ordine di precedenza è:TimeoutInSeconds, ExpiryDate, TimeOfDay.

Per ciascuno degli elementi secondari di <ExpirySettings> sopra indicati, se specifichi l'attributo facoltativo ref nell'elemento secondario, il criterio recupererà il valore di scadenza dalla variabile di contesto denominata. Se la variabile non è definita, il criterio utilizza il valore di testo letterale dell'elemento secondario.

Elemento <Scope>

Enumerazione utilizzata per creare un prefisso per una chiave della cache quando un elemento <Prefix> non viene fornito nell'elemento <CacheKey>.

<Scope>scope_enumeration</Scope>

Predefinito:	"Esclusivo"
Presenza:	Facoltativo
Tipo:	Stringa

L'impostazione <Scope> determina una chiave della cache anteposta in base al valore di <Scope>. Ad esempio, una chiave della cache assume il seguente formato quando l'ambito è impostato su Exclusive:

orgName__envName__apiProxyName__proxy|TargetName__ [ serializedCacheKey ]

Se in <CacheKey> è presente un elemento <Prefix>, questo ha la precedenza su un valore dell'elemento <Scope>. I valori validi includono le enumerazioni di seguito.

Utilizzi l'elemento <Scope> in combinazione con <CacheKey> e <Prefix>. Per saperne di più, consulta Utilizzo delle chiavi della cache.

Valori accettabili

Global	La chiave della cache è condivisa tra tutti i proxy API di cui è stato eseguito il deployment nell'ambiente. La chiave della cache viene anteposta nel formato orgName __ envName __. Se definisci una voce <CacheKey> con <KeyFragment> apiAccessToken e un ambito <Global>, ogni voce viene memorizzata come orgName__envName__apiAccessToken, seguito dal valore serializzato del token di accesso. Per un proxy API di cui è stato eseguito il deployment in un ambiente denominato "test" in un'organizzazione denominata "apifactory", i token di accesso vengono archiviati nella seguente chiave della cache: apifactory__test__apiAccessToken.
Application	Il nome del proxy API viene utilizzato come prefisso. La chiave della cache viene anteposta nel formato orgName__envName__apiProxyName.
Proxy	La configurazione ProxyEndpoint viene utilizzata come prefisso. La chiave della cache viene anteposta nel formato orgName__envName__apiProxyName__proxyEndpointName .
Target	La configurazione TargetEndpoint viene utilizzata come prefisso. Chiave della cache anteposta nel formato orgName__envName__apiProxyName__targetEndpointName .
Exclusive	Valore predefinito. Si tratta dell'opzione più specifica e quindi presenta un rischio minimo di collisioni di spazi dei nomi all'interno di una determinata cache. Il prefisso può avere due forme: Se il criterio è collegato al flusso ProxyEndpoint, il prefisso ha la forma ApiProxyName_ProxyEndpointName. Se il criterio è collegato a TargetEndpoint, il prefisso ha il formato ApiProxyName_TargetName. Chiave della cache anteposta nel modulo orgName__envName__apiProxyName__proxyNameITargetName Ad esempio, la stringa completa potrebbe avere il seguente aspetto: apifactory__test__weatherapi__default__apiAccessToken .

Elemento <Source>

Specifica la variabile il cui valore deve essere scritto nella cache.

<Source>source_variable</Source>

Predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa

Note:

• Gli oggetti JSON vengono archiviati esclusivamente nella cache in memoria (L1).
• Se intendi memorizzare nella cache questi oggetti nella cache persistente (L2), ti consigliamo di serializzarli in un formato stringa.
• Se segui questa pratica, puoi utilizzare in modo efficace la cache L2 e massimizzare l'efficienza della memorizzazione nella cache.
• Per saperne di più, consulta Elementi interni della cache.
  

Note sull'utilizzo

Utilizza questo criterio per la memorizzazione nella cache per uso generico. In fase di runtime, il criterio <PopulateCache> scrive i dati della variabile specificata nell'elemento <Source> nella cache specificata nell'elemento <CacheResource>. Puoi utilizzare gli elementi <CacheKey>, <Scope> e <Prefix> per specificare una chiave che puoi utilizzare dalla policy <LookupCache> per recuperare il valore. Utilizza l'elemento <ExpirySettings> per configurare la scadenza del valore memorizzato nella cache.

La memorizzazione nella cache generica con i criteri PopulateCache, LookupCache e InvalidateCache utilizza una cache che configuri o una cache condivisa inclusa per impostazione predefinita. Nella maggior parte dei casi, la cache condivisa sottostante dovrebbe soddisfare le tue esigenze. Per utilizzare questa cache, ometti semplicemente l'elemento <CacheResource>.

Limiti della cache: si applicano vari limiti della cache, ad esempio dimensioni del nome e del valore, numero totale di cache, numero di elementi in una cache ed scadenza.

Per saperne di più sul datastore sottostante, consulta la sezione Elementi interni della cache.

Informazioni sulla crittografia della cache

Apigee e Apigee hybrid (versione 1.4 e successive): i dati di cache e KVM sono sempre criptati.

Codici di errore

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>