PopulateCache-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Konfiguriert, wie im Cache gespeicherte Werte zur Laufzeit geschrieben werden sollen.

Die PopulateCache-Richtlinie dient zum Schreiben von Einträgen in einem kurzfristigen Cache für allgemeine Zwecke. Sie wird in Verbindung mit der LookupCache-Richtlinie (zum Lesen von Cache-Einträgen) und der InvalidateCache-Richtlinie (zum Entwerten von Einträgen) verwendet.

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.

Informationen zum Caching der Antworten von Back-End-Ressourcen finden Sie unter Antwort-Cache-Richtlinie.

Elementverweis

Im Folgenden sind die über diese Richtlinie konfigurierbaren Werte aufgeführt.

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache>-Attribute

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

Attribut	Beschreibung	Standard	Presence
name	Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.	–	Erforderlich
continueOnError	Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	false	Optional
enabled	Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.	true	Optional
async	Dieses Attribut wurde verworfen.	false	Verworfen

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

Standard	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence	Optional
Typ	String

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

Standard:	–
Präsenz:	Erforderlich
Typ:	–

<CacheKey> erstellt den Namen jedes Datenelements, das im Cache gespeichert ist.

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.

<CacheResource>-Element

Gibt den Cache an, in dem Nachrichten gespeichert werden sollen.

Lassen Sie dieses Element vollständig weg, wenn diese Richtlinie (und Ihre entsprechenden LookupCache- und InvalidateCache-Richtlinien) den enthaltenen freigegebenen Cache verwenden.

<CacheResource>cache_to_use</CacheResource>

Standard:	–
Präsenz:	Optional
Typ:	String

Weitere Informationen zum Konfigurieren von Caches finden Sie unter Caching für allgemeine Zwecke.

<CacheKey>/<KeyFragment>-Element

Gibt einen Wert an, der im Cache-Schlüssel enthalten sein soll. Geben Sie eine Variable an, auf die nicht länger über das Attribut ref oder über einen festen Wert verwiesen werden soll.

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

Standard:	–
Präsenz:	null oder mehr
Typ:	–

Zur Laufzeit erstellt Apigee den Cache-Schlüssel, indem der vom <Scope>-Element oder <Prefix>-Element abgerufene Wert einer Verkettung der aufgelösten Werte jedes <KeyFragment>-Elements vorangestellt wird. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

Attribute

Attribut	Typ	Standard	Erforderlich	Beschreibung
Ref	String		Nein	Die Variable, aus der der Wert abgerufen wird. Sollte nicht verwendet werden, wenn dieses Element einen Literalwert enthält.

<CacheKey>/<Prefix>-Element

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

<Prefix>prefix_string</Prefix>

Standard:	–
Präsenz:	Optional
Typ:	String

Ein <Prefix>-Element überschreibt jedes <Scope>-Element.

Zur Laufzeit erstellt Apigee den Cache-Schlüssel, indem der vom <Scope>-Element oder <Prefix>-Element abgerufene Wert einer Verkettung der aufgelösten Werte jedes <KeyFragment>-Elements vorangestellt wird. Weitere Informationen finden Sie unter Mit Cache-Schlüsseln arbeiten.

<ExpirySettings>-Element

Gibt an, wann ein Cache-Eintrag ablaufen soll.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Standard:	–
Präsenz:	Erforderlich
Typ:	–

Untergeordnete Elemente von <ExpirySettings>

Verwenden Sie genau ein untergeordnetes Element. In der folgenden Tabelle sind die untergeordneten Elemente von <ExpirySettings> beschrieben:

Untergeordnetes Element	Beschreibung
<TimeoutInSeconds>	Die Anzahl der Sekunden, nach denen ein Cache-Eintrag abläuft. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Dieses Element ersetzt das jetzt eingestellte Element TimeoutInSec.
<ExpiryDate>	Gibt das Datum an, an dem ein Cache-Eintrag ablaufen soll. Geben Sie einen String im Format mm-dd-yyyy an. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Wenn das angegebene Datum in der Vergangenheit liegt, wird für den Cacheeintrag die maximale Gültigkeitsdauer angewendet. Das Maximum beträgt 30 Tage.
<TimeOfDay>	Gibt die Tageszeit an, zu der ein Cache-Eintrag ablaufen soll. Geben Sie einen String im Format HH:mm:ss an. Dabei steht HH für die Stunde im 24-Stunden-Format in der UTC-Zeitzone. Beispiel: 14:30:00 impliziert 14:30 Uhr. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Hinweise: Geben Sie die Zeiten in der Zeitzone koordinierte Weltzeit (UTC) an. Die Notation für Cache-Zeiten entspricht der internationalen Standardschreibweise, die im internationalen Standard ISO 8601 definiert ist.

Sie sollten nur eines der möglichen untergeordneten Elemente angeben. Wenn Sie mehrere Elemente angeben, gilt die folgende Prioritätsreihenfolge:TimeoutInSeconds, ExpiryDate, TimeOfDay.

Wenn Sie bei einem der oben genannten untergeordneten Elemente von <ExpirySettings> das optionale Attribut ref angeben, ruft die Richtlinie den Ablaufwert aus der benannten Kontextvariablen ab. Wenn die Variable nicht definiert ist, wird in der Richtlinie der Literaltextwert des untergeordneten Elements verwendet.

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

Standard:	"Exklusiv"
Präsenz:	Optional
Typ:	String

Mit der Einstellung <Scope> wird ein Cache-Schlüssel festgelegt, dem gemäß des Werts <Scope> etwas vorangestellt wird. Ein Cache-Schlüssel hat beispielsweise folgende Form, wenn der Bereich auf Exclusive eingestellt ist:

orgName__envName__apiProxyName__proxy|TargetName__ [ serializedCacheKey ]

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

Global	Der Cache-Schlüssel wird für alle API-Proxys freigegeben, die in der Umgebung bereitgestellt werden. Der Cache-Schlüssel wird im Format orgName __ envName vorangestellt. Wenn Sie einen <CacheKey>-Eintrag mit dem <KeyFragment>-apiAccessToken und dem Bereich <Global> definieren, wird jeder Eintrag als orgName__envName__apiAccessToken gespeichert, gefolgt vom serialisierten Wert des Zugriffstokens. Für einen API-Proxy, der in einer Umgebung mit dem Namen "Test" in einer Organisation namens "apifactory" bereitgestellt wird, werden Zugriffstoken unter folgendem Cache-Schlüssel gespeichert: apifactory__test__apiAccessToken.
Application	Der API-Proxyname wird als Präfix verwendet. Der Cache-Schlüssel wird im Format orgName__envName__apiProxyName vorangestellt.
Proxy	Die ProxyEndpoint-Konfiguration wird als Präfix verwendet. Der Cache-Schlüssel wird im Format orgName__envName__apiProxyName__proxyEndpointName vorangestellt .
Target	Die TargetEndpoint-Konfiguration wird als Präfix verwendet. Der Cache-Schlüssel wird im Format orgName__envName__apiProxyName__targetEndpointName vorangestellt .
Exclusive	Standard. Dies ist die spezifischste Zuordnung und bedingt daher ein minimales Risiko in Sachen Namespace-Konflikten in einem bestimmten Cache. Das Präfix gibt es in zwei Formen: Wenn die Richtlinie an den Ablauf ProxyEndpoint angehängt wird, hat das Präfix das Format ApiProxyName_ProxyEndpointName. Wenn die Richtlinie unter TargetEndpoint angehängt wird, hat das Präfix das Format ApiProxyName_TargetName. Der Cache-Schlüssel wird im Format orgName__envName__apiProxyName__proxyNameITargetName angehängt. Der vollständige String kann so aussehen: apifactory__test__weatherapi__default__apiAccessToken .

<Source>-Element

Gibt die Variable an, deren Wert in den Cache geschrieben werden soll.

<Source>source_variable</Source>

Standard:	–
Präsenz:	Erforderlich
Typ:	String

Hinweise:

• JSON-Objekte werden ausschließlich im In-Memory-Cache (L1) gespeichert.
• Wenn Sie diese Objekte im persistent cache (L2) (persistenten Cache (L2)) speichern möchten, empfehlen wir, sie in ein string-Format zu serialisieren.
• Wenn Sie diese Vorgehensweise befolgen, können Sie den L2-Cache effektiv nutzen und die Caching-Effizienz maximieren.
• Weitere Informationen finden Sie unter Cache-Internes.
  

Verwendungshinweise

Verwenden Sie diese Richtlinie für das allgemeine Caching im Cache. Zur Laufzeit schreibt die Richtlinie <PopulateCache> Daten aus der Variablen, die Sie im Element <Source> angegeben haben, in den Cache, den Sie im Element <CacheResource> angegeben haben. Sie können die Elemente <CacheKey>, <Scope> und <Prefix> verwenden, um einen Schlüssel anzugeben, mit dem Sie den Wert aus der Richtlinie <LookupCache> abrufen können. Mit dem <ExpirySettings>-Element legen Sie fest, wann der im Cache gespeicherte Wert ablaufen soll.

Das Caching für allgemeine Zwecke mit der PopulateCache-Richtlinie, der LookupCache-Richtlinie und der InvalidateCache-Richtlinie verwendet entweder einen von Ihnen konfigurierten Cache oder einen freigegebenen Cache, der standardmäßig berücksichtigt wird. In den meisten Fällen sollte der zugrunde liegende freigegebene Cache Ihren Anforderungen genügen. Um diesen Cache zu verwenden, lassen Sie einfach das <CacheResource>-Element weg.

Cache-Limits: Es gelten verschiedene Cache-Limits, z. B. Name und Wertgröße, Gesamtzahl der Caches, Anzahl der Elemente in einem Cache und Ablauf.

Weitere Informationen zum zugrunde liegenden Datenspeicher finden Sie unter Interne Strukturen des Cache.

Informationen zur Cache-Verschlüsselung

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

Fehlercodes

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

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP Status	Occurs when
policies.populatecache.EntryCannotBeCached	500	An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

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

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidCacheResourceReference	This error occurs if the <CacheResource> element in the PopulateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFound	The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	populatecache.POP-CACHE-1.failed = true

Example error response

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Example fault rule

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>