Criterio ResponseCache

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

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 grazie a latenza e traffico di rete ridotti.

Probabilmente vedrai che ResponseCache è più utile quando i dati del backend utilizzati dalla tua API vengono aggiornati solo periodicamente. Ad esempio, immagina di avere un'API che espone i dati del bollettino meteo aggiornati solo ogni dieci minuti. Utilizzando ResponseCache per restituire risposte memorizzate nella cache tra un aggiornamento e l'altro, puoi ridurre il numero di richieste che raggiungono il backend. Questo riduce anche il numero di hop di rete.

Per una memorizzazione nella cache a breve termine per uso generico, ti consigliamo di utilizzare il criterio Compila la cache. Questo criterio viene utilizzato in combinazione con il criterio Cache di ricerca (per la lettura delle voci della cache) e con il criterio Invalida cache (per le voci invalidanti).

Samples

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 del criterio.

<?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 dei criteri:

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>

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>

<CacheKey> crea il nome di ciascun dato archiviato nella cache. La chiave viene spesso impostata utilizzando un valore delle intestazioni delle entità o dei parametri di query. In questi casi, devi fare in modo che l'attributo ref dell'elemento specifichi una variabile contenente il valore della chiave.

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

Specifica il numero di secondi dopo i quali una ricerca della cache non riuscita verrà considerata un fallimento della cache. In questo caso, il flusso riprende lungo il percorso cache-miss.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Elemento <CacheResource>

Specifica la cache in cui archiviare i messaggi. Ometti questo elemento per utilizzare la cache condivisa inclusa. Devi specificare una risorsa Cache per nome se vuoi poter cancellare a livello amministrativo le voci contenute nella cache. Per ulteriori informazioni, consulta Cache.

<CacheResource>cache_to_use</CacheResource>

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>

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

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

Attualmente, per impostazione predefinita, questo criterio memorizza nella cache le risposte HTTP con qualsiasi codice di stato possibile. Ciò significa che sia le risposte di errore che quelle riuscite vengono memorizzate nella cache. Ad esempio, le risposte con entrambi i 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. Solo le risposte con codici di stato da 200 a 205 verranno memorizzate nella cache se questo elemento è true. Questi sono gli unici codici di stato HTTP che Edge conteggia come codici di operazione riuscita 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 stabilire), l'impostazione predefinita di questo elemento verrà modificata in true. Consulta le note di rilascio di Apigee per i dettagli.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Elemento <ExpirySettings>

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

Elemento <ExpirySettings>/<ExpiryDate>

Specifica la data di scadenza di una voce della cache. Utilizza il modulo mm-dd-yyyy. Se presente, il pari di questo elemento, <TimeoutInSeconds>, sostituisce <ExpiryDate>.

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

Attributi

<ExpiryDate ref="" />

Elemento <ExpirySettings>/<TimeOfDay>

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

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

Per l'ora del giorno, le impostazioni internazionali e il fuso orario predefiniti varieranno a seconda di dove è in esecuzione il codice (che non è noto al momento della configurazione del criterio). Per informazioni sulla configurazione delle impostazioni internazionali, consulta Creazione e modifica di una cache dell'ambiente.

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

Attributi

Elemento <ExpirySettings>/<TimeoutInSec>

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

Elemento <ExpirySettings>/<TimeoutInsecondi>

Il numero di secondi trascorsi i quali una voce della cache deve scadere. Se presente, questo elemento sostituisce gli 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 l'a riferimento non riceve un valore da duration_variable.

Attributi

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>

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

apifactory__test__weatherapi__16__default__apiAccessToken

Elemento <SkipCacheLookup>

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

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Nell'esempio seguente, se la variabile di 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 <SkipCachePopolazione>

Definisce un'espressione che, se restituisce true in fase di esecuzione, specifica che una scrittura nella cache deve essere saltata. Guarda anche questo video sull'utilizzo di SkipCachePop.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Ad esempio, quanto segue ignorerebbe la scrittura nella cache se il codice di stato della risposta fosse 400 o superiore:

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

Elemento <UseAccettaHeader>

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

Edge utilizza le intestazioni delle richieste Accept, Accept-Encoding, Accept-Language e Accept-Charset per il calcolo della chiave cache. Questo approccio impedisce a un cliente di ottenere un tipo di media che non ha richiesto.

Ad esempio, valuta se due richieste provengono 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 sarà (probabilmente) una risposta in formato gzip. La seconda richiesta leggerà il valore memorizzato nella cache e potrebbe quindi restituire una voce gzip a un client non in grado di leggere gzip.

Per ulteriori informazioni, consulta Configurazione di una chiave cache.

<UseAcceptHeader>false</UseAcceptHeader>

Elemento <UseResponseCacheHeaders>

Imposta su true per fare in modo che le intestazioni delle risposte HTTP vengano prese in considerazione durante l'impostazione della "time to live" (TTL) della risposta nella cache. Se è true, Edge considera i valori delle intestazioni di risposta seguenti, confrontando i valori con quelli impostati da <ExpirySettings> durante l'impostazione della durata:

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

Per ulteriori dettagli, consulta Impostare la scadenza delle voci di cache.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Note sull'utilizzo

La dimensione massima di ciascun oggetto memorizzato nella cache è di 256 kB. Per informazioni dettagliate su come Edge elabora la cache, consulta Elementi interni della cache.

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

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

Impostazione della scadenza delle voci di cache

Come per il criterio popola cache, puoi impostare la scadenza (ovvero la durata) di una voce della cache delle risposte utilizzando l'elemento <ExpirySettings>. Nel criterio ResponseCache, puoi anche fare in modo che Edge consideri le intestazioni di risposta quando sono presenti.

Per utilizzare le intestazioni delle risposte, imposta il valore dell'elemento <UseResponseCacheHeaders> su true. Questa impostazione fa sì che Edge consideri le intestazioni delle risposte, le confronti con il valore impostato da <ExpirySettings>, quindi utilizzi il valore più basso tra i due. Quando prende in considerazione 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 pari a 300
• Una data di Expires tra tre giorni
• Un valore <ExpirySettings> TimeoutInSeconds pari a 600.

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

Configurazione di una chiave cache

Come per i criteri della cache per uso generico, come il criterio Compila la cache, con ResponseCache puoi usare gli elementi <CacheKey> e <Scope> per configurare la creazione di chiavi cache per le voci di cache. Con ResponseCache puoi anche rendere più significative le chiavi cache aggiungendo le intestazioni di risposta Accept ai valori chiave.

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

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.

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate quando viene eseguito un criterio ResponseCache. Per ulteriori informazioni sulle variabili di flusso, consulta le informazioni di riferimento sulle 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 criterio è definito da uno schema XML (.xsd). Come riferimento, gli schemi dei criteri sono disponibili su GitHub.