ResponseCache-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

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.

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.

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>

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. Sie sollten eine CacheResource namentlich angeben, wenn Sie im Cache enthaltene Einträge administrativer löschen möchten. Weitere Informationen dazu finden Sie unter Caches.

<CacheResource>cache_to_use</CacheResource>

Weitere Informationen zum Konfigurieren von Caches finden Sie unter Umgebungs-Cache erstellen und bearbeiten.

<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

Derzeit speichert diese Richtlinie HTTP-Antworten mit einem beliebigen möglichen Statuscode im Cache. Das heißt, sowohl die Erfolgs- als auch die Fehlerantworten werden im Cache gespeichert. Beispielsweise werden Antworten mit den Statuscodes 2xx und 3xx standardmäßig im Cache gespeichert.

Setzen Sie dieses Element auf true, wenn Sie Zielantworten mit HTTP-Fehlerstatuscodes nicht im Cache speichern möchten. Nur Antworten mit Statuscodes von 200 bis 205 werden im Cache gespeichert, wenn dieses Element „true“ ist. Dies sind die einzigen HTTP-Statuscodes, die Edge als „Erfolgscodes“ zählt, und Sie können diese Verknüpfung nicht ändern.

Eine Erläuterung der Antwort-Cache-Muster, in denen dieses Element hilfreich ist, finden Sie in diesem Communitybeitrag.

Hinweis:In einem zukünftigen Release (noch festzulegen) wird sich die Standardeinstellung dieses Elements in „true“ ändern. Weitere Informationen finden Sie in den Apigee-Versionshinweisen.

<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. Informationen zum Konfigurieren der Sprache finden Sie unter Umgebungs-Cache erstellen und bearbeiten.

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

Hinweis: Geben Sie einen Standardwert für die Zeitüberschreitung an, der verwendet wird, wenn der Verweis keinen Wert vom duration_variable empfängt.

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. Weitere Informationen zur Verwendung von SkipCacheLookup finden Sie in diesem Video.

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

Edge verwendet die Anfrageheader Accept, Accept-Encoding, Accept-Language und Accept-Charset beim Berechnen des Cache-Schlüssels. 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 dies wahr ist, berücksichtigt Edge die Werte der folgenden Antwortheader und vergleicht die Werte beim Festlegen der Gültigkeitsdauer mit denen, die von <ExpirySettings> festgelegt wurden:

• 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 dazu, wie Edge den Cache verarbeitet, finden Sie unter Cache-Interna.)

Über die Konfiguration in der ResponseCache-Richtlinie können Sie Edge HTTP-Antwortheader beim Festlegen des Ablaufs von Cache-Einträgen und Cache-Schlüsseln hinzufügen lassen. 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 Edge Antwortheader mit der Richtlinie ResponseCache 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 Edge auch dafür sorgen, dass Antwortheader berücksichtigt werden, wenn sie vorhanden sind.

Wenn Sie Antwortheader verwenden möchten, setzen Sie den Elementwert <UseResponseCacheHeaders> auf „true“. Diese Einstellung veranlasst Edge, die Antwortheader zu berücksichtigen, sie mit dem von <ExpirySettings> festgelegten Wert zu vergleichen und dann den niedrigsten Wert zwischen den beiden zu verwenden. Unter Berücksichtigung der Antwortheader wählt Edge den verfügbaren Wert wie unten 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

Edge for Public Cloud:Der Cache wird nur in PCI- und HIPAA-fähigen Organisationen verschlüsselt. Die Verschlüsselung dieser Organisationen wird während der Bereitstellung der Organisation konfiguriert.

Ablaufvariablen

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

Fehlercodes

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

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