Criterio ResponseCache

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Memorizza nella cache i dati di una risorsa di backend, riducendo il numero di richieste alla risorsa. Come app richieste allo stesso URI, puoi usare questo criterio per restituire le risposte memorizzate nella cache anziché inoltrando queste richieste al server di backend. Il criterio ResponseCache può migliorare la capacità delle prestazioni grazie a latenza ridotta e traffico di rete.

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

Per la memorizzazione nella cache a breve termine per uso generico, valuta la possibilità di utilizzare il criterio Compilazione cache. Questo criterio viene utilizzato insieme al criterio Lookup Cache (per la lettura delle voci della cache) e al Annulla convalida criterio Cache (per voci non valide).

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

<ResponseCache> attributi

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

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

<CacheKey> elemento

Configura un puntatore univoco a un dato archiviato nella cache.

La dimensione delle chiavi cache è limitata a 2 kB.

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

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

In fase di runtime, i valori <KeyFragment> vengono anteposti al Valore dell'elemento <Scope> o valore <Prefix>. Ad esempio, la seguente determina la creazione di una chiave cache 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 ulteriori informazioni, vedi Utilizzo delle chiavi cache.

<CacheLookupTimeoutInSeconds> elemento

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

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

<CacheResource> elemento

Specifica la cache in cui devono essere archiviati i messaggi. Ometti questo elemento per utilizzare l'attributo incluso e la cache condivisa. Devi specificare una CacheResource per nome se vuoi cancellare a livello amministrativo le voci contenute nella cache. Per saperne di più, consulta l'articolo Cache.

<CacheResource>cache_to_use</CacheResource>

Per ulteriori informazioni sulla configurazione delle cache, consulta Creare e modificare un ambiente Cache.

<CacheKey>/<KeyFragment> elemento

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

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

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

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

Utilizzi l'elemento <KeyFragment> in combinazione con <Prefix> e <Scope>. Per ulteriori informazioni, vedi Utilizzo delle chiavi cache.

Attributi

<CacheKey>/<Prefix> elemento

Specifica un valore da utilizzare come prefisso della chiave cache.

<Prefix>prefix_string</Prefix>

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

Utilizzi l'elemento <Prefix> in combinazione con <CacheKey> e <Scope>. Per ulteriori informazioni, vedi Utilizzo delle chiavi cache.

<ExcludeErrorResponse> elemento

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

Imposta questo elemento su true se non vuoi memorizzare il target nella cache risposte con codici di stato di errore HTTP; saranno disponibili solo le risposte con codici di stato da 200 a 205 memorizzato nella cache se questo elemento è vero. Questi sono gli unici codici di stato HTTP che Edge conta come "riuscito" e non puoi cambiare questa associazione.

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

Nota:in una release futura (da determinare), verrà utilizzata l'impostazione predefinita. diventerà true. Vedi Apigee Note di rilascio per maggiori dettagli.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

<ExpirySettings> elemento

Specifica quando deve scadere una voce della cache. Se presente, <TimeoutInSeconds> esegue l'override di <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> elemento

Specifica la data in cui una voce della cache deve scadere. Utilizza il modulo mm-dd-yyyy. Se presente, l'elemento di pari livello di questo elemento, <TimeoutInSeconds>, sostituisce <ExpiryDate>.

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

Attributi

<ExpiryDate ref="" />

<ExpirySettings>/<TimeOfDay> elemento

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

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

Per l'ora del giorno, le impostazioni internazionali e il fuso orario predefiniti variano a seconda di dove si trova il codice (che non è noto quando configuri il criterio). Per informazioni sulla configurazione le impostazioni internazionali, consulta la sezione Creazione e modifica di un della cache di ambiente.

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

Attributi

<ExpirySettings>/<TimeoutInSec> elemento

Il numero di secondi dopo il quale una voce della cache deve scadere.

<ExpirySettings>/<TimeoutInSeconds> elemento

Il numero di secondi dopo il quale una voce della cache deve scadere. Se presente, questo elemento esegue l'override degli 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 dall'attributo duration_variable.

Attributi

<Scope> elemento

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

<Scope>scope_enumeration</Scope>

L'impostazione <Scope> determina una chiave cache che viene anteposta in base al il valore <Scope>. Ad esempio, una chiave cache assume il seguente formato quando l'ambito è impostato su Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

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

Utilizzi l'elemento <Scope> in combinazione con <CacheKey> e <Prefix>. Per ulteriori informazioni, vedi Utilizzo delle chiavi cache.

Valori accettabili

apifactory__test__weatherapi__16__default__apiAccessToken

<SkipCacheLookup> elemento

Definisce un'espressione che, se restituisce true in fase di runtime, specifica la ricerca cache e la cache dovrebbe essere aggiornata. Vedi anche questo video sull'uso 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 cache viene saltata e la cache viene aggiornata.

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

<SkipCachePopulation> elemento

Definisce un'espressione che, se restituisce true in fase di runtime, specifica che una scrittura nel la cache. Vedi anche questo video sull'uso di SkipCacheCache.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Ad esempio, quanto segue ignora la scrittura della cache se il codice di stato della risposta è 400 o superiore:

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

<UseAcceptHeader> elemento

Imposta su true per aggiungere alla chiave cache di una voce di risposta della cache con i valori da Accetta le intestazioni nella risposta.

Edge utilizza Accept, Accept-Encoding e Accept-Language e Accept-Charset durante il calcolo della chiave cache. Questo approccio impedisce ai client di ottenere un tipo di media che non ha richiesto.

Ad esempio, considera se due richieste provengono dallo stesso URL, in cui la prima richiesta accetta gzip, al contrario della seconda. La prima richiesta viene memorizzata nella cache e la voce memorizzata (probabilmente) essere una risposta in formato gzip. La seconda richiesta leggerà il valore memorizzato nella cache e potrebbe quindi restituisce una voce compressa con gzip a un client che non è in grado di leggere gzip.

Per ulteriori informazioni, consulta Configurazione di una chiave cache.

<UseAcceptHeader>false</UseAcceptHeader>

<UseResponseCacheHeaders> elemento

Imposta true per considerare le intestazioni delle risposte HTTP quando imposti l'"ora di pubblicato" (TTL) della risposta nella cache. Quando questo è vero, Edge considera i valori le seguenti intestazioni di risposta, confrontando i valori con quelli impostati <ExpirySettings> quando imposti la durata (TTL):

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Note sull'utilizzo

La dimensione massima per ogni oggetto memorizzato nella cache è 256 kB. (per informazioni dettagliate su come Edge di cache, vedi Cache dati interni.

Tramite la configurazione nel criterio ResponseCache, è possibile fare in modo che Edge includa la risposta HTTP come intestazioni nell'impostazione della scadenza delle voci di cache e delle chiavi cache. In questa sezione viene descritto che puoi utilizzare 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 per le intestazioni delle risposte HTTP.

Impostazione della scadenza delle voci della cache

Come per la sezione Compila Criterio della cache, puoi impostare la scadenza (la sua durata) di una voce di risposta della cache utilizzando il metodo Elemento <ExpirySettings>. Nel criterio ResponseCache puoi anche impostare Edge prendi in considerazione le intestazioni delle risposte, se presenti.

Per utilizzare le intestazioni delle risposte, imposta il valore dell'elemento <UseResponseCacheHeaders> su vero. Questa impostazione fa sì che Edge consideri le intestazioni delle risposte, le confronti con il valore impostato per <ExpirySettings>, quindi utilizza il valore più basso tra i due. Quando considerando le intestazioni della risposta, Edge sceglie il valore disponibile come descritto seguenti:

Ad esempio, immagina 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 Expires tra tre giorni
• Un valore TimeoutInSeconds <ExpirySettings> pari a 600.

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

Configurazione di una chiave cache

Come per i criteri generici relativi alla cache, ad esempio Compila criterio Cache, con ResponseCache per cui utilizzi gli elementi <CacheKey> e <Scope> configurare la creazione di chiavi cache per le voci della cache. Con ResponseCache puoi anche creare chiavi cache più significativi facendo aggiungere le intestazioni Accettate ai valori chiave della risposta.

Per informazioni generali sulla configurazione delle chiavi cache, consulta la sezione 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 in PCI e abilitati per HIPAA le tue organizzazioni. La crittografia per queste organizzazioni viene configurata durante l'organizzazione per eseguire il provisioning.

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 Riferimento per le variabili.

Codici di errore

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

N/A

Example error response

N/A

Schema

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, consulta gli schemi dei criteri sono disponibili su GitHub.