ResponseCache-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Speichert Daten aus einer Backend-Ressource im Cache, wodurch die Anzahl der Anfragen an die Ressource reduziert wird. Wenn Anwendungen Anfragen an denselben URI senden, können Sie mit dieser Richtlinie im Cache gespeicherte Antworten zurückgeben, anstatt diese Anfragen an den Back-End-Server weiterzuleiten. Die ResponseCache-Richtlinie kann die Leistung Ihrer API durch reduzierte Latenz und reduzierten Netzwerktraffic verbessern.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Wahrscheinlich finden Sie ResponseCache am nützlichsten, wenn die von Ihrer API verwendeten Backend-Daten nur in bestimmten Abständen aktualisiert werden. Angenommen, Sie haben eine API, die Wetterberichtsdaten nur alle 10 Minuten aktualisiert. Wenn Sie ResponseCache verwenden, um im Cache gespeicherte Antworten zwischen Aktualisierungen zurückzugeben, können Sie die Anzahl der Anfragen verringern, die das Back-End erreichen. Hierdurch wird auch die Anzahl der Netzwerk-Hops reduziert.

Für kurzfristiges Speichern im Cache für allgemeine Zwecke kann es sinnvoll sein, die PopulateCache-Richtlinie zu verwenden. Diese Richtlinie wird in Verbindung mit der LookupCache-Richtlinie (zum Lesen von Cache-Einträgen) und der InvalidateCache-Richtlinie (zum Entwerten von Einträgen) verwendet.

Beispiele

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>

Elementverweis

Die Elementreferenz beschreibt die Elemente und Attribute der Richtlinie:

<?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>-Attribute

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

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

<CacheKey>-Element

Konfiguriert einen eindeutigen Zeiger auf ein im Cache gespeichertes Datenelement.

Cache-Schlüssel sind auf eine Größe von 2 KB begrenzt.

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

<CacheKey> erstellt den Namen jedes Datenelements, das im Cache gespeichert ist. Der Schlüssel wird häufig mithilfe eines Werts aus Entitäts-Headern oder Abfrageparametern festgelegt. In diesen Fällen hätte das Attribut „ref” des Elements eine Variable enthalten, die den Schlüsselwert enthält.

Zur Laufzeit werden <KeyFragment>-Werte entweder dem <Scope>-Elementwert oder dem <Prefix>-Wert vorangestellt. Das folgende Beispiel führt zu einem Cacheschlüssel von UserToken__apiAccessToken__<value_of_client_id>:

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

Sie verwenden das <CacheKey>-Element zusammen mit <Prefix> und <Scope>. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

<CacheLookupTimeoutInSeconds>-Element

Gibt die Anzahl der Sekunden an, nach denen eine fehlgeschlagene Cache-Suche als Cache-Fehler betrachtet wird. In diesem Fall wird der Ablauf entlang des Cache-Fehler-Pfads fortgesetzt.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

<CacheResource>-Element

Gibt den Cache an, in dem Nachrichten gespeichert werden sollen. Lassen Sie dieses Element aus, um den enthaltenen freigegebenen Cache zu verwenden. Geben Sie einen CacheResource-Namen an, wenn Sie Einträge im Cache administrativ löschen möchten. Weitere Informationen dazu finden Sie unter Caches API.

<CacheResource>cache_to_use</CacheResource>

<CacheKey>/<KeyFragment>-Element

Gibt einen Wert an, der im Cache-Schlüssel enthalten sein muss, um einen Namespace für den Abgleich von Anfragen mit im Cache gespeicherten Antworten zu erstellen.

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

Dabei kann es sich um einen Schlüssel (einen von Ihnen angegebenen statischen Namen) oder um einen Wert (einen dynamischen Eintrag, der durch den Verweis auf eine Variable bestimmt wird) handeln. Alle angegebenen Fragmente werden (plus Präfix) verkettet, um den Cache-Schlüssel zu erstellen.

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

Sie verwenden das <KeyFragment>-Element zusammen mit <Prefix> und <Scope>. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

Attribute

<CacheKey>/<Prefix>-Element

Gibt den Wert an, der als Cache-Schlüsselpräfix verwendet werden soll.

<Prefix>prefix_string</Prefix>

Verwenden Sie diesen Wert anstelle von <Scope>, wenn Sie einen eigenen Wert anstelle eines <Scope>-Aufzählungswerts angeben möchten. Wenn definiert, definiert <Prefix> den Cache-Schlüsselwert für Einträge, die in den Cache geschrieben werden. <Prefix>-Elementwerte überschreiben <Scope>-Elementwerte.

Sie verwenden das <Prefix>-Element zusammen mit <CacheKey> und <Scope>. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

<ExcludeErrorResponse>-Element

Mit dieser Richtlinie können HTTP-Antworten mit beliebigen Statuscodes im Cache gespeichert werden. Das bedeutet, dass sowohl Erfolgs- als auch Fehlerantworten im Cache gespeichert werden können, einschließlich 2xx- und 3xx-Statuscodes.

Legen Sie für dieses Element den Wert true (Standard) fest, um die Fehlerantworten auszuschließen. Legen Sie den Wert auf false fest, wenn Sie Zielantworten mit HTTP-Fehlerstatuscodes nicht aus dem Cache ausschließen möchten.

Eine Erläuterung der Antwortcachemuster, in denen dieses Element hilfreich ist, finden Sie unter Einführung in Antimuster.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

<ExpirySettings>-Element

Gibt an, wann ein Cache-Eintrag ablaufen soll. Wenn vorhanden, überschreibt <TimeoutInSeconds> sowohl <TimeOfDay> als auch <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

Gibt das Datum an, an dem ein Cache-Eintrag ablaufen soll. Verwenden Sie das Format mm-dd-yyyy. Wenn dieses Element vorhanden ist, wird <ExpiryDate> vom gleichgeordneten Element <TimeoutInSeconds> überschrieben.

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

Attribute

<ExpiryDate ref="" />

<ExpirySettings>/<TimeOfDay>-Element

Die Tageszeit, zu der ein Cache-Eintrag ablaufen soll. Verwenden Sie das Format hh:mm:ss. Wenn dieses Element vorhanden ist, wird <TimeOfDay> vom gleichgeordneten Element <TimeoutInSeconds> überschrieben.

Geben Sie die Tageszeit im Format HH:mm:ss ein. Dabei steht HH für die Stunde im 24-Stunden-Format. Beispiel: 14:30:00 für 14:30 Uhr am Nachmittag.

In Bezug auf die Tageszeit variieren die Standardsprache und -zeitzone je nachdem, wo der Code ausgeführt wird. Das ist bei der Konfiguration der Richtlinie nicht bekannt.

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

Attribute

<ExpirySettings>/<TimeoutInSec>-Element

Die Anzahl der Sekunden, nach denen ein Cache-Eintrag abläuft.

<ExpirySettings>/<TimeoutInSeconds>-Element

Die Anzahl der Sekunden, nach denen ein Cache-Eintrag abläuft. Wenn dieses Element vorhanden ist, überschreibt dieses Element seine gleichgeordneten Elemente <TimeOfDay> und <ExpiryDate>.

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

Attribute

<Scope>-Element

Aufzählung, die zum Erstellen eines Präfixes für einen Cache-Schlüssel verwendet wird, wenn das Element <Prefix> nicht im Element <CacheKey> angegeben ist.

<Scope>scope_enumeration</Scope>

Mit der Einstellung <Scope> wird ein Cache-Schlüssel festgelegt, dem gemäß des Werts <Scope> etwas vorangestellt wird. Ein Cache-Schlüssel hat beispielsweise das folgende Format, wenn der Bereich auf Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ] festgelegt ist.

Ist in <CacheKey> ein <Prefix>-Element vorhanden, hat dies vor einem <Scope>-Elementwert Vorrang. Gültige Werte sind folgende Aufzählungen.

Sie verwenden das <Scope>-Element zusammen mit <CacheKey> und <Prefix>. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

Zulässige Werte

apifactory__test__weatherapi__16__default__apiAccessToken

<SkipCacheLookup>-Element

Definiert einen Ausdruck, der angibt, dass die Cache-Suche übersprungen und der Cache aktualisiert werden soll. Voraussetzung ist, dass der Ausdruck zur Laufzeit "true" ergibt. Siehe auch das Video zu ResponseCache-Richtlinien verwenden zur Verwendung von SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Wenn im folgenden Beispiel die bypass-cache-Variable in einem eingehenden Header auf "true" gesetzt ist, wird die Cache-Suche übersprungen und der Cache wird aktualisiert.

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

<SkipCachePopulation>-Element

Definiert einen Ausdruck, der bei Auswertung zur Laufzeit als „true“ angibt, dass ein Schreibvorgang in den Cache übersprungen werden soll. Weitere Informationen zur Verwendung von SkipCachePopulation finden Sie in diesem Video.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Im Folgenden wird beispielsweise der Cache-Schreibvorgang übersprungen, wenn der Statuscode der Antwort 400 oder höher war:

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

<UseAcceptHeader>-Element

Geben Sie true an, damit der Cache-Schlüssel eines Repository-Cache-Eintrags mit Werten aus Antwort-Accept-Headern angehängt wird.

Apigee verwendet für die Berechnung des Cache-Schlüssels die Anfrage-Header Accept, Accept-Encoding, Accept-Language und Accept-Charset. Dieser Ansatz verhindert, dass ein Client einen Medientyp erhält, nach dem er nicht gefragt hat.

Angenommen, zwei Anfragen stammen von derselben URL, wobei die erste Anfrage gzip akzeptiert und die zweite nicht. Die erste Anfrage wird im Cache gespeichert und der im Cache gespeicherte Eintrag ist (wahrscheinlich) eine mit gzip komprimierte Antwort. Die zweite Anfrage liest den im Cache gespeicherten Wert und kann dann einen gzip-Eintrag an einen Client zurückgeben, der gzip nicht lesen kann.

Weitere Informationen finden Sie unter Cache-Schlüssel konfigurieren.

<UseAcceptHeader>false</UseAcceptHeader>

<UseResponseCacheHeaders>-Element

Legen Sie true fest, damit HTTP-Antwortheader beim Festlegen der Gültigkeitsdauer (TTL) der Antwort im Cache berücksichtigt werden. Wenn "true", berücksichtigt Apigee die Werte der folgenden Antwortheader und vergleicht die Werte mit den Werten, die durch <ExpirySettings> festgelegt wurden, als die Gültigkeitsdauer festgelegt wurde.

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

Weitere Informationen finden Sie unter Ablauf von Cache-Eintrag festlegen.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Verwendungshinweise

Die maximale Größe für jedes im Cache gespeicherte Objekt beträgt 256 KB. Ausführliche Informationen zur Verarbeitung des Cache durch Apigee finden Sie unter Interne Strukturen des Cache.

Über die Konfiguration in der ResponseCache-Richtlinie können Sie festlegen, dass Apigee HTTP-Antwortheader für das Festlegen von Ablaufzeiten und Cache-Schlüsseln für Cache-Einträge enthält. In diesem Abschnitt wird beschrieben, wie Sie die Richtlinie mit Headern zur Verwaltung des Cache-Ablaufs und der Cache-Schlüssel verwenden können.

Weitere Informationen dazu, wie Apigee Antwortheader mit der ResponseCache-Richtlinie verarbeitet, finden Sie unter Unterstützung von HTTP-Antwortheadern.

Ablauf von Cache-Eintrag festlegen

Wie auch bei der PopulateCache-Richtlinie können Sie mit dem Element <ExpirySettings> die Gültigkeitsdauer (TTL) eines Antwortcache festlegen. In der ResponseCache-Richtlinie können Sie auch festlegen, dass Apigee Antwortheader berücksichtigt, wenn sie vorhanden sind.

Wenn Sie Antwortheader verwenden möchten, setzen Sie den Elementwert <UseResponseCacheHeaders> auf „true“. Diese Einstellung bewirkt, dass Apigee die Antwortheader berücksichtigt, diese mit dem von <ExpirySettings> festgelegten Wert vergleicht und dann den niedrigsten Wert zwischen den beiden verwendet. Bei der Berücksichtigung von Antwortheadern wählt Apigee den verfügbaren Wert wie nachfolgend beschrieben aus:

Angenommen, eine Antwort wird mit den folgenden Werten im Cache gespeichert:

• Kein Cache-Control s-maxage-Wert
• Ein Cache-Control max-age-Wert von 300
• Ein Expires-Datum in drei Tagen
• Ein <ExpirySettings> TimeoutInSeconds-Wert von 600.

In diesem Fall wird der Wert Cache-Control max-age für die TTL verwendet, da diese unter dem Wert <ExpirySettings> liegt und kein Cache-Control s-maxage-Wert vorhanden ist, der Vorrang vor max-age hat.

Cache-Schlüssel konfigurieren

Wie auch bei Cache-Richtlinien mit allgemeinem Zweck wie der PopulateCache-Richtlinie verwenden Sie ResponseCache mit den Elementen <CacheKey> und <Scope>, um das Erstellen von Cache-Schlüsseln für Cache-Einträge zu konfigurieren. Mit ResponseCache können Sie Cache-Schlüssel auch aussagekräftiger gestalten, indem Sie festlegen, dass Antwort-Accept-Header an Schlüsselwerte angehängt werden.

Allgemeine Informationen zum Konfigurieren von Cache-Schlüsseln finden Sie unter Mit Cache-Schlüsseln arbeiten. Weitere Informationen zur Verwendung von Accept-Headern finden Sie unter <UseAcceptHeader>.

Informationen zur Cache-Verschlüsselung

Apigee und Apigee Hybrid (Version 1.4 und höher): Cache- und KVM-Daten werden immer verschlüsselt.

Ablaufvariablen

Die folgenden vordefinierten Ablaufvariablen werden erfasst, wenn eine ResponseCache-Richtlinie ausgeführt wird. Weitere Informationen zu Ablaufvariablen finden Sie in der Referenz zu Ablaufvariablen.

Fehlercodes

In diesem Abschnitt werden die Fehlermeldungen und Ablaufvariablen beschrieben, die festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Dieses Informationen sind wichtig, wenn Sie Fehlerregeln für einen Proxy entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Fehlercode-Präfix

–

Laufzeitfehler

Diese Richtlinie gibt keine Laufzeitfehler aus.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlervariablen

–

Beispiel für eine Fehlerantwort

–

Schema

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.