本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
PopulateCache 政策會設定在執行階段寫入快取值的方式。
Populate Cache 政策的用途是在短期一般用途快取中寫入項目。 這項政策會與 Lookup Cache 政策 (用於讀取快取項目) 和Invalidated 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> 屬性
下表說明所有政策父項元素的共同屬性：
| 屬性 | 說明 | 預設 | 存在必要性 |
|---|---|---|---|
name |
政策的內部名稱。 您可以選擇使用 |
不適用 | 必填 |
continueOnError |
將其設為 將其設為 |
false | 選用 |
enabled |
設為 設為 |
是 | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。
<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>您會搭配 <Prefix> 和 <Scope> 使用 <CacheKey> 元素。詳情請參閱「處理快取金鑰」。
<CacheResource> 元素
指定訊息的儲存快取。
如果這項政策 (和對應的 LookupCache 和 InvalidateCache 政策) 使用內含的共用快取，請完全省略這個元素。
<CacheResource>cache_to_use</CacheResource>
|
預設值： |
不適用 |
|
外觀狀態： |
選用 |
|
類型： |
字串 |
如要進一步瞭解如何設定快取，請參閱「 一般用途快取」。
<CacheKey> 元素
指定應納入快取金鑰的值。使用 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> 這個元素會取代現已淘汰的 |
<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__proxy|TargetName__ [ serializedCacheKey ]
如果 <CacheKey> 中有 <Prefix> 元素，系統會優先採用該元素的值，而非 <Scope> 元素的值。有效值包括下列列舉。
您會搭配 <CacheKey> 和 <Prefix> 使用 <Scope> 元素。詳情請參閱「處理快取金鑰」。
可接受的值
Global |
快取金鑰會在環境中部署的所有 API Proxy 之間共用。快取金鑰會以 orgName __ envName __ 格式預先附加。 如果您使用 |
Application |
API Proxy 名稱會做為前置字串。 快取金鑰會以 orgName__envName__apiProxyName 格式預先附加。 |
Proxy |
ProxyEndpoint 設定會做為前置字串。 快取金鑰會以「orgName__envName__apiProxyName__proxyEndpointName」orgName__envName__apiProxyName__proxyEndpointName格式加在開頭。 |
Target |
TargetEndpoint 設定會做為前置字串。 快取鍵會預先加上 orgName__envName__apiProxyName__targetEndpointName 格式。 |
Exclusive |
預設值，這是最明確的選項，因此在特定快取中，命名空間發生衝突的風險最低。 前置字元有兩種形式：
快取金鑰會預先加上以下格式： orgName__envName__apiProxyName__proxyNameITargetName 舉例來說，完整字串可能如下所示： apifactory__test__weatherapi__default__apiAccessToken |
<Source> 元素
指定應將值寫入快取的變數。
<Source>source_variable</Source>
|
預設值： |
不適用 |
|
外觀狀態： |
必填 |
|
類型： |
字串 |
使用須知
這項政策適用於一般用途的快取。在執行階段，<PopulateCache> 政策會將您在 <Source> 元素中指定的變數資料，寫入您在 <CacheResource> 元素中指定的快取。您可以使用 <CacheKey>、<Scope> 和 <Prefix> 元素指定金鑰，以便從 <LookupCache> 政策中擷取值。使用 <ExpirySettings> 元素設定快取值應何時過期。
使用 PopulateCache 政策、LookupCache 政策和 InvalidateCache 政策進行一般用途的快取時，會使用您設定的快取，或是預設內含的共用快取。在大多數情況下，底層共用快取應可滿足您的需求。如要使用這個快取，只要省略 <CacheResource> 元素即可。
快取限制：適用各種快取限制，例如名稱和值的大小、快取總數、快取中的項目數和到期時間。
如要進一步瞭解基礎資料存放區，請參閱快取內部機制。
關於快取加密
Apigee 和 Apigee Hybrid (1.4 以上版本)：快取和 KVM 資料一律會加密。
錯誤代碼
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.
| 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. |
build |
CacheNotFound |
The cache specified in the <CacheResource> element does not
exist. |
build |
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>