InvalidateCache 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

設定應如何從快取中清除快取值。

這項政策適用於一般用途的短期快取。這個政策會與 PopulateCache 政策 (用於寫入項目) 和 LookupCache 政策 (用於讀取快取項目) 搭配使用。

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

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

注意：如要在訊息流程外清除快取，且不使用政策，可以改用 Delete caches API。

元素參考資料

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

<InvalidateCache async="false" continueOnError="false" enabled="true" name="policy-name">
    <DisplayName>Policy Name</DisplayName>
    <CacheKey>
        <Prefix>prefix_string</Prefix>
        <KeyFragment ref="variable_reference"/>
        <KeyFragment>fragment_string</KeyFragment>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource>cache_to_use</CacheResource>
    <Scope>scope_enumeration</Scope>
    <CacheContext>
        <APIProxyName>application_that_added_the_entry</APIProxyName>
        <ProxyName>proxy_for_which_data_was_cached</ProxyName>
        <TargetName>endpoint_for_which_data_was_cached</TargetName>
    </CacheContext>
    <PurgeChildEntries>true_to_purge_all_child_entries</PurgeChildEntries>
</InvalidateCache>

<InvalidateCache> 屬性

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

屬性	說明	預設	存在必要性
name	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

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

<CacheContext>/<APIProxyName> 元素

指定新增快取項目的應用程式名稱。

<APIProxyName>application_that_added_the_entry</APIProxyName>

屬性

屬性	說明	預設	存在必要性	類型
ref	含有應用程式名稱的變數。	不適用	選用	字串

<CacheContext> 元素

指定在未指定 Prefix 元素值時，如何建構快取金鑰，或清除其他 API Proxy 新增的快取項目。

<CacheContext>
  <APIProxyName ref="variable_name">application_that_added_the_entry</APIProxyName>
  <TargetName ref="variable_name">endpoint_for_which_data_was_cached</TargetName>
  <ProxyName ref="variable_name">proxy_for_which_data_was_cached</ProxyName>
</CacheContext>

用於建構 CacheKey。如果未使用 CacheKey 前置字串 (即自訂前置字串) 清除其他 API Proxy 新增的快取項目，則 APIProxyName、ProxyName 和 TargetName 的值為必要。

<CacheKey> 元素

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

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

指定要儲存郵件的快取。

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

<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> 元素解析值的串連值，藉此建立快取金鑰。詳情請參閱「處理快取金鑰」。

<CacheContext> 元素/<ProxyName>

指定資料已快取的 Proxy 名稱。

<ProxyName>proxy_for_which_data_was_cached</ProxyName>

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

屬性

屬性	說明	預設	存在必要性	類型
ref	要取得值的變數。如果這個元素含有字面值，則不應使用。	不適用	選用	字串

<PurgeChildEntries> 元素

true，即使將這些項目載入快取的 PopulateCache 政策執行個體也使用了各種 <KeyFragment> 元素，系統仍會清除共用此政策設定的相同 <Prefix> 值的快取項目。

如果使相同前置字元值的所有快取項目失效，即可一次清除多個相關項目。

<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>

預設值：	false
外觀狀態：	選用
類型：	布林值

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

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

<Scope> 設定會根據 <Scope> 值決定要預先加入的快取金鑰。舉例來說，如果範圍設為 Exclusive，快取金鑰會採用下列格式：

orgName__envName__applicationName__proxy|TargetName__ [ serializedCacheKey ]。

如果 <CacheKey> 中有 <Prefix> 元素，系統會優先採用該元素的值，而非 <Scope> 元素的值。<Scope> 元素的有效值如下所示。

詳情請參閱「處理快取金鑰」。

可接受的值

範圍值	說明
Global	環境中部署的所有 API Proxy 都會共用快取金鑰。快取金鑰會以 orgName __ envName __ 格式預先附加。 如果您使用 <KeyFragment> apiAccessToken 和 <Global> 範圍定義 <CacheKey> 項目，每個項目都會儲存為 orgName__envName__apiAccessToken，後面接著存取權杖的序列化值。如果 API 代理伺服器部署在名為「apifactory」的機構中，且環境名為「test」，存取權杖會儲存在下列快取金鑰下：apifactory__test__apiAccessToken。
Application	API Proxy 名稱會做為前置字串。 快取金鑰會以「orgName__envName__applicationName」格式加上前置字串。
Proxy	ProxyEndpoint 設定會做為前置字串。 快取金鑰會以 orgName__envName__applicationName__proxyEndpointName 格式加上前置字元。
Target	TargetEndpoint 設定會做為前置字串。 快取金鑰會以 orgName__envName__applicationName__targetEndpointName 格式預先附加。
Exclusive	預設值，這是最明確的選項，因此在特定快取中，命名空間發生衝突的風險最低。 前置字元有兩種形式： 如果政策附加至 ProxyEndpoint 流程，前置字串的格式為 ApiProxyName_ProxyEndpointName。 如果政策附加在 TargetEndpoint，前置字串的格式為 ApiProxyName_TargetName。 快取鍵的前置字串格式為 orgName__envName__applicationName__proxyNameITargetName 舉例來說，完整字串可能如下所示： apifactory__test__weatherapi__default__apiAccessToken 。

<CacheContext> 元素中的「/<TargetName>」

指定資料快取的目標端點名稱。

<TargetName>endpoint_for_which_data_was_cached</TargetName>

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

屬性

屬性	說明	預設	存在必要性	類型
ref	要取得值的變數。如果這個元素含有字面值，則不應使用。	不適用	選用	字串

使用須知

一般用途快取 (使用 PopulateCache 政策、LookupCache 政策和 InvalidateCache 政策) 會使用您設定的快取，或預設內含的共用快取。在大多數情況下，基礎共用快取應該能滿足您的需求。如要使用這個快取，只要省略 <CacheResource> 元素即可。

如要進一步瞭解如何設定快取，請參閱「一般用途快取」。如要進一步瞭解基礎資料存放區，請參閱「快取內部機制」。

錯誤代碼

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

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

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 InvalidateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFound	This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component.

Fault variables

N/A

Example error response

N/A