Norme di PopulateCache

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

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

Il criterio Populate Cache è progettato per scrivere voci in una cache generica a breve termine. Viene utilizzato in combinazione con il criterio della cache di ricerca (per leggere le voci della cache) e il criterio di invalidazione della cache (per invalidare le voci).

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Per la memorizzazione nella cache delle risposte delle risorse di backend, consulta le norme relative alla 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 Presenza
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:

falso Facoltativo
enabled

Imposta su true per applicare il criterio.

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

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.

Presenza Facoltativo
Tipo Stringa

Elemento <CacheKey>

Configura un puntatore univoco a un dato archiviato nella cache.

Le chiavi della cache hanno una dimensione massima di 2 KB.

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

Valore predefinito:

N/D

Presenza:

Obbligatorio

Tipo:

N/D

<CacheKey> genera il nome di ogni elemento di dati archiviato nella cache.

In fase di esecuzione, ai valori <KeyFragment> viene anteposto il valore dell'elemento <Scope> o il valore <Prefix>. Ad esempio, il seguente genera 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>

L'elemento <CacheKey> viene utilizzato in combinazione con <Prefix> e <Scope>. Per ulteriori informazioni, consulta Utilizzo delle chiavi della cache.

Elemento<CacheResource>

Specifica la cache in cui devono essere archiviati i messaggi.

Ometti completamente questo elemento se questo criterio (e i criteri LookupCache e InvalidateCache corrispondenti) utilizza la cache condivisa inclusa.

<CacheResource>cache_to_use</CacheResource>

Valore predefinito:

N/D

Presenza:

Facoltativo

Tipo:

Stringa

Per scoprire di più sulla configurazione delle cache, consulta Memorizzazione nella cache per uso generale.

Elemento <CacheKey>/<KeyFragment>

Specifica un valore da includere nella chiave della cache. Specifica una variabile da annullare il riferimento con l'attributo ref o un valore fisso.

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

Valore predefinito:

N/D

Presenza:

zero o più

Tipo:

N/D

In fase di esecuzione, 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 ulteriori informazioni, 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 della cache.

<Prefix>prefix_string</Prefix>

Valore predefinito:

N/D

Presenza:

Facoltativo

Tipo:

Stringa

Un elemento <Prefix> ha la precedenza su qualsiasi elemento <Scope>.

In fase di esecuzione, 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 ulteriori informazioni, consulta Utilizzo delle chiavi della cache.

Elemento <ExpirySettings>

Specifica quando deve scadere 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>

Valore 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 deve scadere una voce della cache.

<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 formato mm-dd-yyyy.

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

Se la data specificata è nel passato, il criterio applicherà il valore TTL massimo alla voce memorizzata nella cache. Il periodo di tempo massimo è di 30 giorni.

<TimeOfDay>

Specifica l'ora in cui deve scadere una voce della cache. Specifica una stringa nel formato HH:mm:ss, dove HH rappresenta l'ora su un orologio 24 ore nel fuso orario UTC. Ad esempio, 14:30:00 indica le 14:30 del pomeriggio.

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

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

Con 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 nell'elemento <CacheKey> non è specificato un elemento <Prefix>.

<Scope>scope_enumeration</Scope>

Valore predefinito:

"Esclusiva"

Presenza:

Facoltativo

Tipo:

Stringa

L'impostazione <Scope> determina una chiave della cache che viene anteposta in base al valore <Scope>. Ad esempio, una chiave della cache assumerebbe la seguente forma quando l'ambito è impostato su Exclusive:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

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

L'elemento <Scope> viene utilizzato in combinazione con <CacheKey> e <Prefix>. Per ulteriori informazioni, 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 premessa nel formato orgName __ envName __.

Se definisci una voce <CacheKey> con il valore <KeyFragment> apiAccessToken e un ambito <Global>, ogni voce viene archiviata come orgName__envName__apiAccessToken, seguita dal valore serializzato del token di accesso. Per un proxy API di cui è stato eseguito il deployment in un ambiente chiamato 'test' in un'organizzazione chiamata '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 di ProxyEndpoint viene utilizzata come prefisso.

La chiave della cache viene anteposta nel formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .

Target

La configurazione di TargetEndpoint viene utilizzata come prefisso.

Chiave della cache anteposta nel formato orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .

Exclusive

Valore predefinito. È il valore più specifico e, pertanto, presenta un rischio minimo di collisioni di spazi dei nomi all'interno di una determinata cache.

Il prefisso può essere di due tipi:

  • Se il criterio è associato al flusso ProxyEndpoint, il prefisso è del formato ApiProxyName_ProxyEndpointName.
  • Se il criterio è allegato a TargetEndpoint, il prefisso è del tipo ApiProxyName_TargetName.

Chiave della cache anteposta nel formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

Ad esempio, la stringa completa potrebbe avere il seguente aspetto:

apifactory__test__weatherapi__16__default__apiAccessToken
.

Elemento <Source>

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

<Source>source_variable</Source>

Valore predefinito:

N/D

Presenza:

Obbligatorio

Tipo:

Stringa

Note sull'utilizzo

Utilizza questo criterio per la memorizzazione nella cache per uso generico. In fase di esecuzione, il criterio <PopulateCache> scrive i dati dalla 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 dal criterio <LookupCache> per recuperare il valore. Utilizza l'elemento <ExpirySettings> per configurare la scadenza del valore memorizzato nella cache.

La memorizzazione nella cache per uso generico con il criterio PopulateCache, il criterio LookupCache e il criterio InvalidateCache utilizza una cache configurata o una cache condivisa inclusa per impostazione predefinita. Nella maggior parte dei casi, la cache condivisa di base dovrebbe soddisfare le tue esigenze. Per utilizzare questa cache, ometti semplicemente l'elemento <CacheResource>.

Limiti della cache: vengono applicati diversi limiti della cache, ad esempio le dimensioni del nome e del valore, il numero totale di cache, il numero di elementi in una cache e la scadenza.

Per saperne di più sul datastore sottostante, consulta Informazioni interne sulla cache.

Informazioni sulla crittografia della cache

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

Codici di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Si verifica quando
policies.populatecache.EntryCannotBeCached 500 Una voce non può essere memorizzata nella cache. L'oggetto messaggio memorizzato nella cache non è un'istanza di una classe serializzabile.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore Causa Correggi
InvalidCacheResourceReference Questo errore si verifica se l'elemento <CacheResource> nel criterio PopulateCache è impostato su un nome che non esiste nell'ambiente in cui viene eseguito il deployment del proxy API.
CacheNotFound La cache specificata nell'elemento <CacheResource> non esiste.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. populatecache.POP-CACHE-1.failed = true

Esempio di risposta di errore

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

Esempio di regola di errore

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