Criteri di memorizzazione nella cache in Gestione APIAPI Management caching policies

Questo argomento fornisce un riferimento per i seguenti criteri di Gestione API.This topic provides a reference for the following API Management policies. Per informazioni sull'aggiunta e sulla configurazione dei criteri, vedere Criteri di Gestione API.For information on adding and configuring policies, see Policies in API Management.

Criteri di memorizzazione nella cache Caching policies

Recupera dalla cache Get from cache

Usare il criterio cache-lookup per eseguire una ricerca nella cache e restituire una risposta valida memorizzata nella cache, se disponibile.Use the cache-lookup policy to perform cache look up and return a valid cached response when available. Questo criterio può essere applicato nei casi in cui il contenuto della risposta rimane statico in un periodo di tempo.This policy can be applied in cases where response content remains static over a period of time. La memorizzazione delle risposte nella cache riduce la larghezza di banda e i requisiti di elaborazione imposti sul server Web back-end e riduce la latenza percepita dagli utenti delle API.Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Nota

Questo criterio deve essere associato a un criterio Archivia nella cache corrispondente.This policy must have a corresponding Store to cache policy.

Istruzione del criterioPolicy statement

<cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" downstream-caching-type="none | private | public" must-revalidate="true | false" allow-private-response-caching="@(expression to evaluate)">  
  <vary-by-header>Accept</vary-by-header>  
  <!-- should be present in most cases -->  
  <vary-by-header>Accept-Charset</vary-by-header>  
  <!-- should be present in most cases -->  
  <vary-by-header>Authorization</vary-by-header>  
  <!-- should be present when allow-authorized-response-caching is "true"-->  
  <vary-by-header>header name</vary-by-header>  
  <!-- optional, can repeated several times -->  
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>  
  <!-- optional, can repeated several times -->  
</cache-lookup>  

EsempiExamples

EsempioExample

<policies>  
    <inbound>  
        <base />  
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="true">  
            <vary-by-query-parameter>version</vary-by-query-parameter>  
        </cache-lookup>           
    </inbound>  
    <outbound>  
        <cache-store duration="seconds" />  
        <base />          
    </outbound>  
</policies>  

Esempio con espressioni di criteriExample using policy expressions

Questo esempio mostra come per configurare la durata della memorizzazione nella cache di Gestione API corrispondente alla memorizzazione delle risposte nella cache del serivzio back-end, come specificato dalla direttiva Cache-Control del servizio in questione.This example shows how to to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. Per una dimostrazione relativa alla configurazione e all'uso di questi criteri, vedere l' episodio 177 di Cloud Cover su altre funzionalità di Gestione API con Vlad Vinogradsky e passare direttamente al minuto 25:25.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management reponse cache duration with Cache-Control headers sent by the backend service. -->  

<!-- Copy this snippet into the inbound section -->  
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >  
  <vary-by-header>Accept</vary-by-header>  
  <vary-by-header>Accept-Charset</vary-by-header>  
</cache-lookup>  

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the deafult value of 5 min if none is found  -->  
<cache-store duration="@{  
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");  
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;  
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;  
  }"  
 />  

Per altre informazioni, vedere Espressioni di criteri e Variabile di contesto.For more information, see Policy expressions and Context variable.

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
cache-lookupcache-lookup Elemento radice.Root element. Yes
vary-by-headervary-by-header Avviare la memorizzazione delle risposte nella cache per ogni valore dell'intestazione specificata, come ad esempio Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host e If-Match.Start caching responses per value of specified header, such as Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host, If-Match. NoNo
vary-by-query-parametervary-by-query-parameter Avvia risposte di memorizzazione nella cache per ogni valore dei parametri di query specificati.Start caching responses per value of specified query parameters. Immettere un singolo parametro o più parametri.Enter a single or multiple parameters. Usare un punto e virgola (;) come separatore.Use semicolon as a separator. Se non è specificato alcun nome, verranno usati tutti i parametri di query.If none are specified, all query parameters are used. NoNo

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
allow-private-response-cachingallow-private-response-caching Se impostato su true, consente la memorizzazione nella cache delle richieste contenenti un'intestazione di autorizzazione.When set to true, allows caching of requests that contain an Authorization header. NoNo falsefalse
downstream-caching-typedownstream-caching-type Questo attributo deve essere impostato su uno dei valori seguenti.This attribute must be set to one of the following values.

- none - Non è consentita la memorizzazione nella cache downstream.- none - downstream caching is not allowed.
- private - È consentita la memorizzazione nella cache downstream privata.- private - downstream private caching is allowed.
- public - È consentita la memorizzazione nella cache downstream privata e condivisa.- public - private and shared downstream caching is allowed.
NoNo nessunonone
must-revalidatemust-revalidate Quando è abilitata la memorizzazione nella cache downstream, questo attributo attiva o disattiva la direttiva di controllo di memorizzazione della cache must-revalidate nelle risposte del gateway.When downstream caching is enabled this attribute turns on or off the must-revalidate cache control directive in gateway responses. NoNo truetrue
vary-by-developervary-by-developer Impostare su true per memorizzare le risposte nella cache per ogni chiave sviluppatore.Set to true to cache responses per developer key. NoNo falsefalse
vary-by-developer-groupsvary-by-developer-groups Impostare su true per memorizzare le risposte nella cache per ogni ruolo utente.Set to true to cache responses per user role. NoNo falsefalse

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: in ingressoPolicy sections: inbound

  • Ambiti del criterio: API, operazione, prodottoPolicy scopes: API, operation, product

Archivia nella cache Store to cache

Il criterio cache-store memorizza nella cache le risposte in base alle impostazioni specificate per la cache.The cache-store policy caches responses according to the specified cache settings. Questo criterio può essere applicato nei casi in cui il contenuto della risposta rimane statico in un periodo di tempo.This policy can be applied in cases where response content remains static over a period of time. La memorizzazione delle risposte nella cache riduce la larghezza di banda e i requisiti di elaborazione imposti sul server Web back-end e riduce la latenza percepita dagli utenti delle API.Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Nota

Questo criterio deve essere associato a un criterio Recupera dalla cache corrispondente.This policy must have a corresponding Get from cache policy.

Istruzione del criterioPolicy statement

<cache-store duration="seconds" />  

EsempiExamples

EsempioExample

<policies>  
    <inbound>  
        <base />  
          <cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" downstream-caching-type="none | private | public" must-revalidate="true | false">  
                <vary-by-query-parameter>parameter name</vary-by-query-parameter> <!-- optional, can repeated several times -->  
        </cache-lookup>  
    </inbound>  
    <outbound>  
        <base />  
            <cache-store duration="3600" />  
    </outbound>  
</policies>  

Esempio con espressioni di criteriExample using policy expressions

Questo esempio mostra come per configurare la durata della memorizzazione nella cache di Gestione API corrispondente alla memorizzazione delle risposte nella cache del serivzio back-end, come specificato dalla direttiva Cache-Control del servizio in questione.This example shows how to to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. Per una dimostrazione relativa alla configurazione e all'uso di questi criteri, vedere l' episodio 177 di Cloud Cover su altre funzionalità di Gestione API con Vlad Vinogradsky e passare direttamente al minuto 25:25.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management reponse cache duration with Cache-Control headers sent by the backend service. -->  

<!-- Copy this snippet into the inbound section -->  
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >  
  <vary-by-header>Accept</vary-by-header>  
  <vary-by-header>Accept-Charset</vary-by-header>  
</cache-lookup>  

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the deafult value of 5 min if none is found  -->  
<cache-store duration="@{  
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");  
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;  
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;  
  }"  
 />  

Per altre informazioni, vedere Espressioni di criteri e Variabile di contesto.For more information, see Policy expressions and Context variable.

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
cache-storecache-store Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
durationduration Durata (TTL, Time-To-Live) delle voci memorizzate nella cache, in secondi.Time-to-live of the cached entries, specified in seconds. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere utilizzato nelle sezioni e negli ambiti di criteri seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: in uscitaPolicy sections: outbound

  • Ambiti del criterio: API, operazione, prodottoPolicy scopes: API, operation, product

Recupera valore dalla cache Get value from cache

Usare il criterio cache-lookup-value per eseguire la ricerca nella cache in base alla chiave e restituiscono un valore memorizzato nella cache.Use the cache-lookup-value policy to perform cache lookup by key and return a cached value. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri.The key can have an arbitrary string value and is typically provided using a policy expression.

Nota

Questo criterio deve essere associato a un criterio Archivia valore nella cache corrispondente.This policy must have a corresponding Store value in cache policy.

Istruzione del criterioPolicy statement

<cache-lookup-value key="cache key value"   
    default-value="value to use if cache lookup resulted in a miss"   
    variable-name="name of a variable looked up value is assigned to" />  

EsempioExample

Per ulteriori informazioni ed esempi su questo criterio, vedere Memorizzazione nella cache personalizzata in Gestione API di Azure.For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-lookup-value  
    key="@("userprofile-" + context.Variables["enduserid"])"    
    variable-name="userprofile" />  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
cache-lookup-valuecache-lookup-value Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
default-valuedefault-value Un valore che verrà assegnato alla variabile se la ricerca della chiave nella cache non produce risultati.A value that will be assigned to the variable if the cache key lookup resulted in a miss. Se questo attributo viene omesso, viene assegnato null.If this attribute is not specified, null is assigned. NoNo null
keykey Valore della chiave della cache da usare nella ricerca.Cache key value to use in the lookup. Yes N/DN/A
variable-namevariable-name Nome della variabile di contesto a cui verrà assegnato il valore cercato, se la ricerca ha esito positivo.Name of the context variable the looked up value will be assigned to, if lookup is successful. Se la ricerca non produce risultati, alla variabile sarà assegnato il valore dell'attributo default-value o null, se l'attributo default-value è omesso.If lookup results in a miss, the variable will be assigned the value of the default-value attribute or null, if the default-value attribute is omitted. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, outbound, backend, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: global, API, operation, productPolicy scopes: global, API, operation, product

Archivia valore nella cache Store value in cache

cache-store-value esegue l'archiviazione nella cache in base alla chiave.The cache-store-value performs cache storage by key. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri.The key can have an arbitrary string value and is typically provided using a policy expression.

Nota

Questo criterio deve essere associato a un criterio Recupera valore dalla cache corrispondente.This policy must have a corresponding Get value from cache policy.

Istruzione del criterioPolicy statement

<cache-store-value key="cache key value" value="value to cache" duration="seconds" />  

EsempioExample

Per ulteriori informazioni ed esempi su questo criterio, vedere Memorizzazione nella cache personalizzata in Gestione API di Azure.For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-store-value  
    key="@("userprofile-" + context.Variables["enduserid"])"  
    value="@((string)context.Variables["userprofile"])" duration="100000" />  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
cache-store-valuecache-store-value Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
durationduration Il valore verrà memorizzato nella cache per il valore di durata specificato, espresso in secondi.Value will be cached for the provided duration value, specified in seconds. Yes N/DN/A
keykey La chiave della cache in cui verrà archiviato il valore.Cache key the value will be stored under. Yes N/DN/A
valuevalue Il valore da memorizzare nella cache.The value to be cached. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, outbound, backend, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: global, API, operation, productPolicy scopes: global, API, operation, product

Rimuovi valore dalla cache Remove value from cache

cache-remove-value elimina un elemento memorizzato nella cache identificato in base alla chiave.The cache-remove-value deletes a cached item identified by its key. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri.The key can have an arbitrary string value and is typically provided using a policy expression.

Istruzione del criterioPolicy statement


<cache-remove-value key="cache key value"/>  

EsempioExample


<cache-remove-value key="@("userprofile-" + context.Variables["enduserid"])"/>  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
cache-remove-valuecache-remove-value Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
keykey La chiave del valore memorizzato in precedenza nella cache da rimuovere dalla cache.The key of the previously cached value to be removed from the cache. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes .

  • Sezioni del criterio: inbound, outbound, backend, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: global, API, operation, productPolicy scopes: global, API, operation, product

Passaggi successiviNext steps

Per altre informazioni sull'uso dei criteri, vedere Criteri di Gestione API.For more information working with policies, see Policies in API Management.