Criterio ResponseCache

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Memorizza nella cache i dati di una risorsa di backend, riducendo il numero di richieste alla risorsa. Poiché le app effettuano richieste allo stesso URI, puoi utilizzare questo criterio per restituire risposte memorizzate nella cache anziché inoltrare queste richieste al server di backend. Il criterio ResponseCache può migliorare le prestazioni della tua API riducendo la latenza e il traffico di rete.

Probabilmente troverai ResponseCache più utile quando i dati di backend utilizzati dall'API vengono aggiornati solo periodicamente. Ad esempio, supponiamo di avere un'API che espone i dati dei bollettini meteo aggiornati solo ogni dieci minuti. Utilizzando ResponseCache per restituire le risposte memorizzate nella cache tra gli aggiornamenti, puoi ridurre il numero di richieste che raggiungono il backend. In questo modo si riduce anche il numero di hop di rete.

Per la memorizzazione nella cache a breve termine per uso generico, valuta la possibilità di utilizzare il criterio Popola cache. Questo criterio 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).

Esempi

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi delle norme.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

Attributi <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

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>

<CacheKey> crea il nome di ogni dato memorizzato nella cache. La chiave viene spesso impostata utilizzando un valore delle intestazioni delle entità o dei parametri di query. In questi casi, l'attributo ref dell'elemento specifica una variabile contenente il valore della chiave.

In fase di runtime, i valori di <KeyFragment> vengono anteposti al valore dell'elemento <Scope> o al valore di <Prefix>. Ad esempio, il seguente 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>

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

Elemento <CacheLookupTimeoutInSeconds>

Specifica il numero di secondi dopo i quali una ricerca nella cache senza esito positivo verrà considerata un fallimento della cache. In questo caso, il flusso riprende lungo il percorso di fallimento della cache.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Elemento <CacheResource>

Specifica la cache in cui devono essere archiviati i messaggi. Ometti questo elemento per utilizzare la cache condivisa inclusa. Devi specificare una CacheResource per nome se vuoi poter cancellare amministrativamente le voci contenute nella cache. Per saperne di più, consulta Cache.

<CacheResource>cache_to_use</CacheResource>

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

Elemento <CacheKey>/<KeyFragment>

Specifica un valore da includere nella chiave della cache, creando uno spazio dei nomi per la corrispondenza tra le richieste e le risposte memorizzate nella cache.

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

Può trattarsi di una chiave (un nome statico che fornisci) o di un valore (una voce dinamica impostata facendo riferimento a una variabile). Tutti i frammenti specificati combinati (più il prefisso) vengono concatenati per creare la chiave della cache.

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

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

Attributi

Elemento <CacheKey>/<Prefix>

Specifica un valore da utilizzare come prefisso della chiave cache.

<Prefix>prefix_string</Prefix>

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

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

Elemento <ExcludeErrorResponse>

Attualmente, per impostazione predefinita, questo criterio memorizza nella cache le risposte HTTP con qualsiasi codice di stato possibile. Ciò significa che vengono memorizzate nella cache sia le risposte positive che quelle di errore. Ad esempio, le risposte con codici di stato 2xx e 3xx vengono memorizzate nella cache per impostazione predefinita.

Imposta questo elemento su true se non vuoi memorizzare nella cache le risposte di destinazione con codici di stato di errore HTTP; se questo elemento è true, verranno memorizzate nella cache solo le risposte con codici di stato da 200 a 205. Questi sono gli unici codici di stato HTTP che Edge considera "riusciti" e non puoi modificare questa associazione.

Per una discussione sui pattern della cache delle risposte in cui questo elemento è utile, consulta questo post della community.

Nota:in una release futura (da determinare), l'impostazione predefinita di questo elemento verrà modificata in true. Per informazioni dettagliate, consulta le note di rilascio di Apigee.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Elemento <ExpirySettings>

Specifica la scadenza di una voce della cache. Se presente, <TimeoutInSeconds> ha la precedenza su <TimeOfDay> e <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

<ExpirySettings>/<ExpiryDate> element

Specifica la data di scadenza di una voce della cache. Utilizza il modulo mm-dd-yyyy. Se presente, l'elemento di pari livello, <TimeoutInSeconds>, esegue l'override di <ExpiryDate>.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Attributi

<ExpiryDate ref="" />

Elemento <ExpirySettings>/<TimeOfDay>

L'ora del giorno in cui una voce della cache deve scadere. Utilizza il modulo hh:mm:ss . Se presente, l'elemento di pari livello, <TimeoutInSeconds>, esegue l'override di <TimeOfDay>.

Inserisci l'ora del giorno nel formato HH:mm:ss, dove HH rappresenta l'ora su un orologio a 24 ore. Ad esempio, 14:30:00 per le 14:30.

Per l'ora del giorno, le impostazioni internazionali e il fuso orario predefiniti variano a seconda di dove viene eseguito il codice (che non è noto quando configuri le norme). Per informazioni sulla configurazione delle impostazioni locali, vedi Creare e modificare una cache dell'ambiente.

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Attributi

Elemento <ExpirySettings>/<TimeoutInSec>

Il numero di secondi dopo i quali una voce della cache deve scadere.

Elemento <ExpirySettings>/<TimeoutInSeconds>

Il numero di secondi dopo i quali una voce della cache deve scadere. Se presente, questo elemento sovrascrive i relativi elementi di pari livello, <TimeOfDay> e <ExpiryDate>.

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

Nota:fornisci un valore di timeout predefinito da utilizzare se il riferimento non riceve un valore da duration_variable.

Attributi

Elemento <Scope>

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

<Scope>scope_enumeration</Scope>

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

apifactory__test__weatherapi__16__default__apiAccessToken

Elemento <SkipCacheLookup>

Definisce un'espressione che, se restituisce il valore true in fase di runtime, specifica che la ricerca nella cache deve essere ignorata e la cache deve essere aggiornata. Vedi anche questo video sull'utilizzo di SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Dall'esempio seguente, se la variabile bypass-cache è impostata su true in un'intestazione in entrata, la ricerca nella cache viene ignorata e la cache viene aggiornata.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

Elemento <SkipCachePopulation>

Definisce un'espressione che, se restituisce il valore true in fase di runtime, specifica che una scrittura nella cache deve essere ignorata. Vedi anche questo video sull'utilizzo di SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Ad esempio, il seguente codice salterebbe la scrittura della cache se il codice di stato della risposta fosse 400 o superiore:

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

Elemento <UseAcceptHeader>

Imposta true per aggiungere alla chiave cache di una voce della cache di risposta i valori delle intestazioni Accept della risposta.

Edge utilizza le intestazioni delle richieste Accept, Accept-Encoding, Accept-Language e Accept-Charset quando calcola la chiave cache. Questo approccio impedisce a un client di ottenere un tipo di media che non ha richiesto.

Ad esempio, considera il caso in cui arrivano due richieste dallo stesso URL, dove la prima richiesta accetta gzip e la seconda no. La prima richiesta verrà memorizzata nella cache e la voce memorizzata nella cache (probabilmente) sarà una risposta compressa con gzip. La seconda richiesta leggerà il valore memorizzato nella cache e potrebbe quindi restituire una voce compressa con gzip a un client che non è in grado di leggere gzip.

Per saperne di più, consulta Configurazione di una chiave della cache.

<UseAcceptHeader>false</UseAcceptHeader>

Elemento <UseResponseCacheHeaders>

Imposta questo valore su true per fare in modo che le intestazioni della risposta HTTP vengano prese in considerazione quando viene impostata la "durata" (TTL) della risposta nella cache. Se questa condizione è vera, Edge prende in considerazione i valori delle seguenti intestazioni della risposta, confrontandoli con quelli impostati da <ExpirySettings> quando imposta il time to live:

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

Per ulteriori dettagli, consulta Impostazione della scadenza delle voci della cache.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Note sull'utilizzo

La dimensione massima di ogni oggetto memorizzato nella cache è 256 KB. (Per informazioni dettagliate su come Edge elabora la cache, vedi Elementi interni della cache.)

Tramite la configurazione nel criterio ResponseCache, puoi fare in modo che Edge includa le intestazioni della risposta HTTP nell'impostazione della scadenza delle voci della cache e delle chiavi cache. Questa sezione descrive come utilizzare i criteri con le intestazioni per gestire la scadenza della cache e le chiavi cache.

Per saperne di più su come Edge gestisce le intestazioni delle risposte con il criterio ResponseCache, consulta Supporto per le intestazioni della risposta HTTP.

Impostazione della scadenza delle voci della cache

Come per il criterio Popola cache, puoi impostare la scadenza di una voce della cache delle risposte (il relativo tempo di permanenza) utilizzando l'elemento <ExpirySettings>. Nella policy ResponseCache, puoi anche fare in modo che Edge prenda in considerazione le intestazioni della risposta quando sono presenti.

Per utilizzare le intestazioni di risposta, imposta il valore dell'elemento <UseResponseCacheHeaders> su true. Questa impostazione fa sì che Edge prenda in considerazione le intestazioni della risposta, le confronti con il valore impostato da <ExpirySettings> e utilizzi il valore più basso tra i due. Quando considera le intestazioni della risposta, Edge sceglie il valore disponibile come descritto di seguito:

Ad esempio, supponiamo che una risposta venga memorizzata nella cache con i seguenti valori:

• Nessun valore Cache-Control s-maxage
• Un valore Cache-Control max-age di 300
• Una data Expires tra tre giorni
• Un valore <ExpirySettings> TimeoutInSeconds di 600.

In questo caso, il valore Cache-Control max-age verrà utilizzato per il TTL perché è inferiore al valore <ExpirySettings> e perché non esiste un valore Cache-Control s-maxage (che ha la precedenza su max-age).

Configurazione di una chiave della cache

Come per le norme di memorizzazione nella cache per uso generico, ad esempio la norma Popola cache, con ResponseCache utilizzi gli elementi <CacheKey> e <Scope> per configurare la creazione delle chiavi della cache per le voci della cache. Con ResponseCache puoi anche rendere le chiavi cache più significative aggiungendo le intestazioni Accept della risposta ai valori delle chiavi.

Per informazioni generali sulla configurazione delle chiavi cache, consulta Utilizzo delle chiavi cache. Per informazioni sull'utilizzo delle intestazioni Accept, vedi <UseAcceptHeader>.

Informazioni sulla crittografia della cache

Edge per il 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.

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate quando viene eseguita una policy ResponseCache. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili.

Codici di errore

Questa sezione descrive i messaggi di errore e le variabili di flusso che vengono impostati quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per un proxy. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Prefisso codice di errore

N/A

Errori di runtime

Questo criterio non genera errori di runtime.

Errori di deployment

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

Variabili di errore

N/A

Esempio di risposta di errore

N/A

Schema

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.