PopulateCache 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

設定如何在執行階段寫入快取值。

「Populate Cache」政策旨在針對短期通用快取寫入項目。這項政策會與快取查詢政策 (用於讀取快取項目) 和撤銷快取政策 (用於撤銷項目) 搭配使用。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

如要快取後端資源的回應，請參閱回應快取政策。

元素參照

下列為您列出可在本政策中設定的元素。

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

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

<CacheKey> 元素

設定快取中儲存的資料片段的專屬指標。

快取鍵的大小上限為 2 KB。

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

預設值：	不適用
外觀狀態：	必填
類型：	不適用

<CacheKey> 會建構快取中儲存的每個資料的名稱。

在執行階段，<KeyFragment> 值會在開頭加上 <Scope> 元素值或 <Prefix> 值。舉例來說，以下結果會產生 UserToken__apiAccessToken__<value_of_client_id> 的快取鍵：

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

您可以將 <CacheKey> 元素與 <Prefix> 和 <Scope> 搭配使用。詳情請參閱「使用快取鍵」。

<CacheResource> 元素

指定訊息應儲存在哪個快取中。

如果這項政策 (以及對應的 LookupCache 和 InvalidateCache 政策) 使用內含的共用快取，請完全省略這個元素。

<CacheResource>cache_to_use</CacheResource>

預設值：	不適用
外觀狀態：	選用
類型：	字串

如要進一步瞭解如何設定快取，請參閱「 通用快取」。

<CacheKey>/<KeyFragment> 元素

指定應納入快取金鑰的值。使用 ref 屬性或固定值，指定要解除參照的變數。

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

預設值：	不適用
外觀狀態：	零或更多
類型：	不適用

在執行階段，Apigee 會將從 <Scope> 元素或 <Prefix> 元素取得的值，前置至各個 <KeyFragment> 元素的解析值串連字串，藉此建立快取索引鍵。詳情請參閱「使用快取鍵」。

屬性

屬性	類型	預設	必填	說明
ref	字串		否	取得值的變數。如果此元素包含文字值，則不應使用此屬性。

<CacheKey>/<Prefix> 元素

指定要用於做為快取金鑰前置字串的固定值。

<Prefix>prefix_string</Prefix>

預設值：	不適用
外觀狀態：	選用
類型：	字串

<Prefix> 元素會覆寫任何 <Scope> 元素。

在執行階段，Apigee 會將從 <Scope> 元素或 <Prefix> 元素取得的值，前置至各個 <KeyFragment> 元素的解析值串連字串，藉此建立快取索引鍵。詳情請參閱「使用快取鍵」。

<ExpirySettings> 元素

指定快取項目的到期時間。

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

預設值：	不適用
外觀狀態：	必填
類型：	不適用

<ExpirySettings> 的子元素

請使用單一子項。下表說明 <ExpirySettings> 的子元素：

子元素	說明
<TimeoutInSeconds>	快取項目應在幾秒後過期。 <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> 這個元素取代了現已淘汰的 TimeoutInSec 元素。
<ExpiryDate>	指定快取項目的到期日。請在 mm-dd-yyyy 的格式中指定字串。 <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> 如果指定的日期已過，政策會將最長存留時間套用至快取項目。最長 30 天。
<TimeOfDay>	指定快取項目的到期時間。以 HH:mm:ss 格式指定字串，其中 HH 代表世界標準時間時區的 24 小時制小時。舉例來說，14:30:00 表示下午 2:30。 <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> 注意事項： 指定 世界標準時間 (UTC) 時區的時間。 填入快取時間符號時，請遵循國際標準 ISO 8601 中定義的國際標準日期符號。

您應只指定一個可能的子項。如果您指定多個元素，優先順序為：TimeoutInSeconds、ExpiryDate、TimeOfDay。

對於上述 <ExpirySettings> 的每個子項，如果您在子項上指定選用的 ref 屬性，政策就會從命名內容變數中擷取到期日值。如果未定義變數，政策會使用子元素的文字值。

<Scope> 元素

當 <CacheKey> 元素未提供 <Prefix> 元素時，用於建構快取鍵前置字串的列舉。

<Scope>scope_enumeration</Scope>

預設值：	「獨家」
外觀狀態：	選用
類型：	字串

<Scope> 設定會決定快取索引鍵，並根據 <Scope> 值加在前面。舉例來說，當範圍設為 Exclusive 時，快取索引鍵會採用以下格式：

orgName__envName__apiProxyName__proxy|TargetName__ [ serializedCacheKey ]

如果 <CacheKey> 中含有 <Prefix> 元素，則會取代 <Scope> 元素值。有效值包括下列列舉。

您可以將 <Scope> 元素與 <CacheKey> 和 <Prefix> 搭配使用。詳情請參閱「使用快取鍵」。

可接受的值

Global	快取索引鍵會在環境中部署的所有 API Proxy 之間共用。快取索引鍵會以 orgName __ envName __ 的格式置於前方。 如果您使用 <KeyFragment> apiAccessToken 和 <Global> 範圍定義 <CacheKey> 項目，每個項目都會儲存為 orgName__envName__apiAccessToken，後面接著存放存取權杖的序列化值。如果 API 代理程式是在名為「apifactory」的機構中，以名為「test」的環境中部署，存取權杖會儲存在下列快取鍵下：apifactory__test__apiAccessToken。
Application	API Proxy 名稱會用做前置字串。 快取鍵的開頭格式為 orgName__envName__apiProxyName。
Proxy	ProxyEndpoint 設定會做為前置字串使用。 快取鍵會以 orgName__envName__apiProxyName__proxyEndpointName 的格式置於前方。
Target	使用 TargetEndpoint 設定做為前置字串。 快取鍵前置格式為 orgName__envName__apiProxyName__targetEndpointName。
Exclusive	預設值，這是最具體的做法，因此在特定快取中發生命名空間衝突的風險也最低。 前置字串有兩種形式： 如果政策已附加至 ProxyEndpoint 流程，前置字串的格式為 ApiProxyName_ProxyEndpointName。 如果政策附加在 TargetEndpoint，前置字串的格式為 ApiProxyName_TargetName。 快取索引鍵，格式為 orgName__envName__apiProxyName__proxyNameITargetName 例如，完整字串可能如下所示： apifactory__test__weatherapi__default__apiAccessToken 。

<Source> 元素

指定應將值寫入快取的變數。

<Source>source_variable</Source>

預設值：	不適用
外觀狀態：	必填
類型：	字串

附註：

• JSON 物件專門儲存在記憶體快取 (L1) 中。
• 如果您想在持久性快取 (L2) 中快取這些物件，建議您將這些物件序列化為 字串格式。
• 遵循這項做法，您就能有效運用 L2 快取，並將快取效率發揮到極致。
• 詳情請參閱「快取內部」。
  

使用須知

請將這項政策用於一般用途快取。在執行階段，<PopulateCache> 政策會將您在 <Source> 元素中指定的變數資料寫入您在 <CacheResource> 元素中指定的快取。您可以使用 <CacheKey>、<Scope> 和 <Prefix> 元素指定可從 <LookupCache> 政策擷取值的鍵。使用 <ExpirySettings> 元素設定快取值的到期時間。

搭配 PopulateCache 政策、LookupCache 政策和 InvalidateCache 政策的一般用途快取會使用您設定的快取，或預設包含的共用快取。在大多數情況下，底層共用快取應可滿足您的需求。如要使用此快取，請省略 <CacheResource> 元素。

快取限制：適用各種快取限制，例如名稱和值大小、快取總數、快取中的項目數量和到期日。

如要進一步瞭解基礎資料儲存庫，請參閱「快取內部資訊」。

關於快取加密

Apigee 和 Apigee hybrid (1.4 以上版本)：快取和 KVM 資料一律會加密。

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼	HTTP 狀態	發生時機
policies.populatecache.EntryCannotBeCached	500	無法快取項目。快取的訊息物件並非可序列化的類別例項。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

提示：需要協助解決錯誤嗎？按一下「修正」欄中的 ，即可查看詳細的疑難排解資訊。

錯誤名稱	原因	修正
InvalidCacheResourceReference	如果 PopulateCache 政策中的 <CacheResource> 元素設為在部署 API Proxy 的環境中不存在的名稱，就會發生這個錯誤。
CacheNotFound	<CacheResource> 元素中指定的快取不存在。

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
fault.name="fault_name"	fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name 是擲回錯誤的政策的使用者指定名稱。	populatecache.POP-CACHE-1.failed = true

錯誤回應範例

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

錯誤規則範例

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