InvalidateCache 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

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

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

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

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

元素參照

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

<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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 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 代理程式新增的快取項目。

<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。如果未使用快取鍵前置字串 (也就是自訂前置字串) 來清除其他 API 代理程式新增的快取項目，則必須提供 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>

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

<CacheResource> 元素

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

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

<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> 元素的解析值串連字串，藉此建立快取索引鍵。詳情請參閱「使用快取鍵」。

<CacheContext>/<ProxyName> 元素

指定資料快取的 Proxy 名稱。

<ProxyName>proxy_for_which_data_was_cached</ProxyName>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

屬性

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

<PurgeChildEntries> 元素

true 會清除共用為這項政策設定的相同 <Prefix> 值的快取項目，即使將這些項目載入快取的 PopulateCache 政策 例項也使用了各種 <KeyFragment> 元素。

您可以讓所有相同前置字元值的快取項目失效，一次清除多個相關項目。

<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>

預設值：

false

外觀狀態：

 選用

類型：

布林值

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設值：

「獨家」

外觀狀態：

 選用

類型：

字串

<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> 元素即可。

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

錯誤代碼

本節將說明在政策觸發錯誤時，系統會設定的錯誤訊息和流程變數。如果您要為 Proxy 開發錯誤規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

錯誤代碼前置字串

不適用

執行階段錯誤

這項政策不會擲回任何執行階段錯誤。

部署錯誤

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

錯誤名稱 原因 修正
InvalidCacheResourceReference 如果 InvalidateCache 政策中的 <CacheResource> 元素設為在部署 API Proxy 的環境中不存在的名稱，就會發生這個錯誤。
CacheNotFound 如果未在特定的 Message Processor 元件上建立錯誤訊息中提及的特定快取，就會發生這個錯誤。

錯誤變數

不適用

錯誤回應範例

不適用