您正在查看 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<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> 這個元素會取代現已淘汰的 |
<ExpiryDate> |
指定快取項目的到期日。以 <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> 如果指定日期是過去的日期,這項政策會將存留時間上限套用至快取項目。最長不得超過 30 天。 |
<TimeOfDay> |
指定快取項目的到期時間。
以 <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 __ 的格式。 如果您使用 |
Application |
系統會使用 API Proxy 名稱做為前置字串。 快取金鑰的前面會加上 orgName__envName__apiProxyName, |
Proxy |
系統會使用 ProxyEndpoint 設定做為前置字串。 快取金鑰的前面會加上 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName。 |
Target |
TargetEndpoint 設定會做為前置字串使用。 前置的快取金鑰,格式為 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName。 |
Exclusive |
預設。這是最具體的做法,因此在指定快取中會造成命名空間衝突的風險降到最低。 前置字串為下列其中一種格式:
前方的快取金鑰,格式為 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 部署的環境中,就會發生這個錯誤。 |
build |
CacheNotFound |
<CacheResource> 元素中指定的快取不存在。 |
build |
錯誤變數
系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "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>