Criterio ResponseCache

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

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

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni sull'utilizzo, consulta Tipi di criteri.

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 dei bollettini meteo aggiornati solo ogni dieci minuti. Utilizzando ResponseCache per restituire le risposte memorizzate nella cache tra un aggiornamento e l'altro, 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, ti consigliamo di utilizzare il criterio PopulateCache. Questo criterio viene utilizzato insieme al criterio LookupCache (per la lettura delle voci della cache) e Criterio InvalidateCache (per voci non valide).

Guarda il video seguente per un'introduzione al criterio Cache di risposta.

Esempi

Cache di 10 minuti

Questo esempio mostra come conservare le risposte memorizzate nella cache per 10 minuti.

Supponi di avere un'API al seguente URL:

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

Stai utilizzando il parametro di query w come chiave cache. Apigee controlla il valore del parametro di query w ogni volta che viene ricevuta una richiesta. Se nella cache è presente una risposta valida (ovvero non scaduta), il messaggio di risposta memorizzato nella cache viene restituito al client richiedente.

Ora immagina di avere un criterio ResponseCache configurato come segue.

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

La prima volta che il proxy API riceve un messaggio di richiesta per il seguente URL, la risposta viene memorizzata nella cache. Alla seconda richiesta entro 10 minuti viene eseguita una ricerca nella cache: la risposta memorizzata nella cache viene restituita all'app senza alcuna richiesta inoltrata al servizio di backend.

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

Salta la ricerca nella cache

L'esempio seguente mostra come fare in modo che la ricerca cache venga saltata e come fare in modo che la cache aggiornato. Vedi anche questo video sull'uso di SkipCacheLookup.

La condizione facoltativa SkipCacheLookup (se configurata) viene valutata nel percorso della richiesta. Se la condizione restituisce true, la ricerca nella cache viene saltata e la cache viene aggiornata.

Un utilizzo comune dell'aggiornamento della cache condizionale è una condizione che definisce un'intestazione HTTP specifica che fa sì che la condizione venga valutata come vera. Un'applicazione client basata su script potrebbe essere configurata in modo da inviare periodicamente una richiesta con l'intestazione HTTP appropriata, causando l'aggiornamento della cache delle risposte.

Ad esempio, immagina una chiamata a un'API all'URL seguente:

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

Ora immagina il seguente criterio ResponseCache configurato su quel proxy. Tieni presente che la condizione bypass-cache è impostata su 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>

Per ulteriori informazioni sulle condizioni, consulta la sezione Variabili e condizioni.

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>

&lt;ResponseCache&gt; 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:

Attributo Descrizione Predefinito Presenza
name

Il nome interno del criterio. Il valore dell'attributo name può Deve contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, puoi utilizzare l'elemento <DisplayName> per etichettare il criterio in l'editor proxy della UI 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 fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

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

&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>
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 memorizzato 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 esecuzione, ai valori <KeyFragment> viene anteposto il valore dell'elemento <Scope> o <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, vedi Utilizzo delle chiavi cache.

Elemento <CacheLookupTimeoutInSeconds>

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>

Valore predefinito:

30

Presenza:

 Facoltativo

Tipo:

Numero intero

&lt;CacheResource&gt; elemento

Specifica la cache in cui devono essere archiviati i messaggi. Ometti questo elemento per utilizzare la cache condivisa inclusa. Devi specificare un CacheResource per nome se vuoi poter cancellare a livello amministrativo le voci contenute nella cache. Per saperne di più, consulta l'API Caches.

<CacheResource>cache_to_use</CacheResource>

Valore predefinito:

N/D

Presenza:

 Facoltativo

Tipo:

Stringa

Elemento <CacheKey>/<KeyFragment>

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>

Valore predefinito:

N/D

Presenza:

 Facoltativo

Tipo:

N/D

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> insieme a <Prefix> e <Scope>. Per ulteriori informazioni, consulta Utilizzo delle chiavi della cache.

Attributi

Attributo Tipo Predefinito Obbligatorio Descrizione
riferimento string No

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

&lt;CacheKey&gt;/&lt;Prefix&gt; elemento

Specifica un valore da utilizzare come prefisso della chiave cache.

<Prefix>prefix_string</Prefix>

Valore predefinito:

N/D

Presenza:

 Facoltativo

Tipo:

Stringa

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

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

Elemento <ExcludeErrorResponse>

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 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 Apigee conteggia come "riuscito" e non puoi cambiare questa associazione.

Per una discussione sui pattern di Response Cache in cui questo elemento è utile, consulta Introduzione agli anti-pattern.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Valore predefinito:

falso

Presenza:

 Facoltativo

Tipo:

Booleano

&lt;ExpirySettings&gt; elemento

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

Valore predefinito:

N/D

Presenza:

 Obbligatorio

Tipo:

N/D

Elemento <ExpirySettings>/<ExpiryDate>

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

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

Valore predefinito:

N/D

Presenza:

 Facoltativo

Tipo:

Stringa

Attributi

<ExpiryDate ref="" />
Attributo Descrizione Predefinito Presenza Tipo
ref

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

 N/D Facoltativo Stringa

&lt;ExpirySettings&gt;/&lt;TimeOfDay&gt; elemento

L'ora alla quale deve scadere una voce della cache. Utilizza il modulo hh:mm:ss. Se presente, l'elemento fratello <TimeoutInSeconds> di questo elemento sostituisce <TimeOfDay>.

Inserisci l'ora del giorno nel formato HH:mm:ss, dove HH indica l'ora su un orologio 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 viene eseguito il codice (non è possibile conoscerli quando configuri il criterio).

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

Predefinita:

 N/D

Presenza:

 Facoltativo

Tipo:

Stringa

Attributi

Attributo Descrizione Predefinito Presenza Tipo
riferimento Variabile con il valore dell'ora di scadenza. N/D Facoltativo Stringa

&lt;ExpirySettings&gt;/&lt;TimeoutInSec&gt; elemento

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

Nome errore Causa Correggi
InvalidTimeout Se l'elemento <CacheLookupTimeoutInSeconds> del criterio ResponseCache viene impostato su un numero negativo, il deployment del proxy API non va a buon fine.
InvalidCacheResourceReference Questo errore si verifica se l'elemento <CacheResource> in un criterio ResponseCache è impostato su un nome che non esiste nell'ambiente in cui viene eseguito il deployment del proxy API.
ResponseCacheStepAttachmentNotAllowedReq Questo errore si verifica se lo stesso criterio ResponseCache è associato a più percorsi di richiesta all'interno di qualsiasi flusso di un proxy API.
ResponseCacheStepAttachmentNotAllowedResp Questo errore si verifica se lo stesso criterio ResponseCache è collegato a più percorsi di risposta all'interno di qualsiasi flusso di un proxy API.
InvalidMessagePatternForErrorCode Questo errore si verifica se l'elemento <SkipCacheLookup> o <SkipCachePopulation> in un criterio ResponseCache contiene una condizione non valida.
CacheNotFound Questo errore si verifica se la cache specifica menzionata nel messaggio di errore non è stata creata su un componente specifico dell'processore di messaggi.

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, consulta gli schemi dei criteri sono disponibili su GitHub.