PopulateCache 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

設定執行階段的快取值寫入方式。

「填入快取」政策是專為在短期一般用途快取中寫入項目而設計。這項政策可與查詢快取政策 (用於讀取快取項目) 和撤銷快取政策 (用於撤銷項目) 搭配使用。

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

元素參照

以下列出可以在這項政策中設定的元素。

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

下表說明所有政策父項元素的通用屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素，在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

 不適用 需要
continueOnError

如果設為 false，即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true，即可在政策失敗後繼續執行資料流。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用這項政策。即使政策仍附加在流程中，系統也不會強制執行政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性外，您還可以使用不同的自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

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

指定應包含在快取金鑰中的值，藉此建立命名空間來比對要求與快取回應。

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

預設：

不適用

所在地：

 選用

類型：

不適用

這可以是鍵 (您提供的靜態名稱) 或值 (藉由參照變數所設定的動態項目)。系統會將所有指定的片段 (加上前置字串) 串連起來，以建立快取金鑰。

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

請將 <KeyFragment> 元素與 <Prefix> 和 <Scope> 搭配使用。詳情請參閱「使用快取金鑰」。

屬性

屬性 類型 預設 需要 說明
參考資料 字串 否

要取得這個值的變數。如果這個元素包含常值，請勿使用。

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

預設：

不適用

所在地：

 選用

類型：

字串

如果您要自行指定值，而非 <Scope> 列舉值，請使用這個值，而非 <Scope>。如已定義，<Prefix> 會在寫入快取的項目前面加上快取金鑰值。<Prefix> 元素值會覆寫 <Scope> 元素值。

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

<ExpirySettings> 元素

指定快取項目的到期時間。當 <TimeoutInSeconds> 存在時，會同時覆寫 <TimeOfDay> 和 <ExpiryDate>。

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

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

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

<Scope> 元素

未在 <CacheKey> 元素中提供 <Prefix> 元素時，用來建構快取金鑰前置字串的列舉。

<Scope>scope_enumeration</Scope>

預設：

「獨家」

所在地：

 選用

類型：

字串

<Scope> 設定會決定根據 <Scope> 值前面加上的快取金鑰。例如，當範圍設為 Exclusive 時，快取金鑰會採用以下形式：

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

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

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

可接受的值

Global

快取金鑰會由環境部署的所有 API Proxy 共用。快取金鑰的前面會加上 orgName __ envName __ 的格式。

如果您使用 <KeyFragment> apiAccessToken 和 <Global> 範圍定義 <CacheKey> 項目，每個項目都會儲存為 orgName__envName__apiAccessToken，後面接著存取權杖的序列化值。如果 API Proxy 部署在名為「apifactory」的機構中，即部署在「test」的環境中，存取權杖會儲存在下列快取金鑰底下：apifactory__test__apiAccessToken。
Application

系統會使用 API Proxy 名稱做為前置字串。

快取金鑰的前面會加上 orgName__envName__apiProxyName，
Proxy

系統會使用 ProxyEndpoint 設定做為前置字串。

快取金鑰的前面會加上 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName。
Target

TargetEndpoint 設定會做為前置字串使用。

前置的快取金鑰，格式為 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName。
Exclusive

預設。這是最具體的做法，因此在指定快取中會造成命名空間衝突的風險降到最低。

前置字串為下列其中一種格式：

  • 如果政策已附加至 ProxyEndpoint 資料流，前置字串的格式為 ApiProxyName_ProxyEndpointName。
  • 如果附加在 TargetEndpoint 的政策，前置字串的格式為 ApiProxyName_TargetName。

前方的快取金鑰，格式為 orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

例如，整個字串可能如下所示：

apifactory__test__weatherapi__16__default__apiAccessToken
。

<Source> 元素

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

<Source>source_variable</Source>

預設：

不適用

所在地：

 需要

類型：

字串

使用須知

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

依據 PopulateCache 政策、LookupCache 政策和 InvalidateCache 政策執行一般目的，系統會使用您設定的快取，或是預設包含的共用快取。在大多數情況下，基本的共用快取應可滿足您的需求。如要使用這個快取，只要省略 <CacheResource> 元素即可。

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

如要進一步瞭解基礎資料儲存庫，請參閱「快取內部快取」。如要進一步瞭解如何設定快取，請參閱「建立及編輯環境快取」一文。

關於快取加密

公有雲的邊緣：快取只會在啟用 PCI 和健康保險流通與責任法案的機構中加密。這些機構的加密作業會在機構佈建期間設定。

錯誤代碼

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 發生時機
policies.populatecache.EntryCannotBeCached 500 無法快取項目。快取的訊息物件不是 Serializable 類別的例項。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

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

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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>