Criterio PopulateCache

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

Consente di configurare il modo in cui devono essere scritti i valori memorizzati nella cache in fase di runtime.

Il criterio Compila la cache è progettato per scrivere voci in una cache per uso generico a breve termine. Viene utilizzato in combinazione con il criterio Cache di ricerca (per la lettura delle voci della cache) e con il criterio Annulla convalida cache (per le voci invalidanti).

Per memorizzare le risposte delle risorse di backend nella cache, consulta il Criterio 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 della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

N/A Obbligatorie
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio.

false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

true Facoltativo
async

Questo attributo è obsoleto.

false Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta 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/A

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 cache hanno una dimensione massima di 2 kB.

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

Predefinito:

N/A

Presenza:

Obbligatorie

Tipo:

N/A

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

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

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

Puoi utilizzare l'elemento <CacheKey> insieme a <Prefix> e <Scope>. Per ulteriori informazioni, consulta Utilizzo delle chiavi cache.

Elemento<CacheResource>

Specifica la cache in cui archiviare 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>

Predefinito:

N/A

Presenza:

Facoltativo

Tipo:

Stringa

Per saperne di più sulla configurazione delle cache, consulta Creazione e modifica di una cache di ambiente.

Elemento <CacheKey>/<KeyFragment>

Specifica un valore che deve essere incluso nella chiave cache, creando uno spazio dei nomi per le richieste corrispondenti alle risposte memorizzate nella cache.

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

Predefinito:

N/A

Presenza:

Facoltativo

Tipo:

N/A

Può essere una chiave (un nome statico fornito da te) o un valore (una voce dinamica impostata facendo riferimento a una variabile). Tutti i frammenti specificati (più il prefisso) vengono concatenati per creare la chiave cache.

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

Puoi utilizzare l'elemento <KeyFragment> insieme a <Prefix> e <Scope>. Per ulteriori informazioni, consulta Utilizzo delle chiavi cache.

Attributi

Attributo Tipo Predefinito Obbligatorie Descrizione
rif stringa No

La variabile da cui ricavare il valore. Non deve essere utilizzato se questo elemento contiene un valore letterale.

Elemento <CacheKey>/<Prefix>

Specifica un valore da utilizzare come prefisso della chiave cache.

<Prefix>prefix_string</Prefix>

Predefinito:

N/A

Presenza:

Facoltativo

Tipo:

Stringa

Utilizza questo valore anziché <Scope> quando vuoi specificare un tuo valore anziché un valore enumerato da <Scope>. Se definito, <Prefix> antepone il valore della chiave cache per le voci scritte nella cache. Un valore dell'elemento <Prefix> sostituisce un valore dell'elemento <Scope>.

Puoi utilizzare l'elemento <Prefix> insieme a <CacheKey> e <Scope>. Per ulteriori informazioni, consulta Utilizzo delle chiavi cache.

Elemento <ExpirySettings>

Specifica la scadenza di una voce della cache. Se presente, <TimeoutInSeconds> sostituisce sia <TimeOfDay> che <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>

Predefinito:

N/A

Presenza:

Obbligatorie

Tipo:

N/A

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 trascorsi i quali una voce della cache deve scadere.

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

Questo elemento sostituisce l'elemento TimeoutInSec, ora obsoleto.

<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à la durata massima alla voce memorizzata nella cache. Questo periodo massimo è di 30 giorni.

<TimeOfDay>

Specifica l'ora del giorno in cui deve scadere una voce della cache. Specifica una stringa nel formato HH:mm:ss, dove HH rappresenta l'ora nel formato a 24 ore nel fuso orario UTC. Ad esempio, 14:30:00 implica 2: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 dei precedenti elementi secondari di <ExpirySettings>, 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 viene definita, il criterio utilizza il valore di testo letterale dell'elemento figlio.

Elemento <Scope>

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

<Scope>scope_enumeration</Scope>

Predefinito:

"Esclusiva"

Presenza:

Facoltativo

Tipo:

Stringa

L'impostazione <Scope> determina una chiave cache da anteporre al valore <Scope>. Ad esempio, una chiave cache assumerà il seguente formato quando l'ambito è impostato su Exclusive:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

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

Puoi utilizzare l'elemento <Scope> insieme a <CacheKey> e <Prefix>. Per ulteriori informazioni, consulta Utilizzo delle chiavi cache.

Valori accettabili

Global

La chiave cache è condivisa tra tutti i proxy API di cui è stato eseguito il deployment nell'ambiente. La chiave cache è anteposta nel formato orgName __ orgName __.

Se definisci una voce <CacheKey> con l'apiAccessToken <KeyFragment> 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 denominato "test" in un'organizzazione denominata "apilabs", i token di accesso vengono archiviati nella seguente chiave cache: apifactory__test__apiAccessToken.

Application

Il nome del proxy API viene utilizzato come prefisso.

La chiave cache è anteposta nel formato orgName__envName__apiProxyName.

Proxy

come prefisso viene utilizzata la configurazione ProxyEndpoint.

La chiave cache viene anteposta nel formato orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .

Target

come prefisso viene utilizzata la configurazione TargetEndpoint.

La chiave cache è anteposta nel formato orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .

Exclusive

Predefinita. Questa è la più specifica e pertanto presenta un rischio minimo di collisioni dello spazio dei nomi all'interno di una data cache.

Il prefisso può avere due forme:

  • Se il criterio è associato al flusso ProxyEndpoint, il prefisso è nel formato ApiProxyName_ProxyEndpointName.
  • Se il criterio è collegato all'indirizzo TargetEndpoint, il formato del prefisso è ApiProxyName_TargetName.

La chiave 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 il cui valore deve essere scritto nella cache.

<Source>source_variable</Source>

Predefinito:

N/A

Presenza:

Obbligatorie

Tipo:

Stringa

Note sull'utilizzo

Utilizza questo criterio per la memorizzazione nella cache per uso generico. In fase di runtime, il criterio <PopulateCache> scrive i dati dalla variabile specificata nell'elemento <Source> alla 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 da te 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 le dimensioni di nome e valore, il numero totale di cache, il numero di elementi contenuti in una cache e la scadenza.

Per saperne di più sull'archivio dati sottostante, consulta Elementi interni della cache. Per saperne di più sulla configurazione delle cache, consulta Creazione e modifica di una cache dell'ambiente.

Informazioni sulla crittografia della cache

Edge per cloud pubblico: la cache è criptata solo nelle organizzazioni abilitate per PCI e HIPAA. La crittografia per queste organizzazioni viene configurata durante il provisioning dell'organizzazione.

Codici di errore

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

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

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

Errori di deployment

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

Nome 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di 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>