InvalidateCache 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

這項政策適用於一般用途的短期快取。這項政策會與「填入快取政策」 (用於寫入項目) 和「查詢快取政策」 (用於讀取快取項目) 搭配使用。

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

元素參考資料

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

<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> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<CacheContext>/<APIProxyName> 元素

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

<APIProxyName>application_that_added_the_entry</APIProxyName>

屬性

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

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

預設值：

N/A

外觀狀態：

 必填

類型：

N/A

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

預設值：

N/A

外觀狀態：

 選用

類型：

字串

如要進一步瞭解如何設定快取，請參閱「建立及編輯環境快取」。

<CacheKey> 元素

指定應納入快取鍵的值，為比對要求與快取回應建立命名空間。

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

預設值：

N/A

外觀狀態：

 選用

類型：

N/A

這可以是鍵 (您提供的靜態名稱)，也可以是值 (透過參照變數設定的動態項目)。所有指定的片段 (加上前置字串) 會串連在一起，形成快取金鑰。

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

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

屬性

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

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

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

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

<CacheContext> 元素

指定資料快取的 Proxy 名稱。

<ProxyName>proxy_for_which_data_was_cached</ProxyName>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

屬性

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

<PurgeChildEntries> 元素

true，清除共用此政策所設定 <KeyFragment> 元素值的快取項目。系統不會考慮快取金鑰其他部分的值，例如 <Prefix> 元素中的值。

請注意，必須指定 <KeyFragment> 元素。如果不是，將 <PurgeChildEntries> 設為 true 可能會導致清除快取中的所有項目。

如果想一次清除多個相關項目，可以將相同鍵片段值的所有快取項目設為無效。

<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>

預設值：

false

外觀狀態：

 選用

類型：

布林值

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設值：

「Exclusive」

外觀狀態：

 選用

類型：

字串

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

orgName__envName__applicationName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]。

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

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

可接受的值

範圍值 說明
Global

環境中部署的所有 API Proxy 都會共用快取金鑰。快取金鑰會以 orgName __ envName __ 格式預先附加。

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

API Proxy 名稱會做為前置字串。

快取金鑰會以「orgName__envName__applicationName」格式加在前面。
Proxy

ProxyEndpoint 設定會做為前置字串。

快取金鑰會以以下格式加在前面： orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName 。
Target

TargetEndpoint 設定會做為前置字串。

快取金鑰會以「orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName」的形式預先附加。
Exclusive

預設。這是最明確的選項，因此在特定快取中，命名空間發生衝突的風險最低。

前置字元有兩種形式：

  • 如果政策附加至 ProxyEndpoint 流程，前置字串的格式為 ApiProxyName_ProxyEndpointName。
  • 如果政策附加在 TargetEndpoint，前置字元格式為「ApiProxyName_TargetName」ApiProxyName_TargetName。

快取金鑰會以 orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName 格式加上前置字串

舉例來說，完整字串可能如下所示：

apifactory__test__weatherapi__16__default__apiAccessToken
。

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

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

<TargetName>endpoint_for_which_data_was_cached</TargetName>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

屬性

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

使用須知

使用 Populate Cache 政策、LookupCache 政策和 InvalidateCache 政策的一般用途快取，會使用您設定的快取或預設包含的共用快取。在大多數情況下，底層共用快取應可滿足您的需求。如要使用這個快取，只要省略 <CacheResource> 元素即可。

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

錯誤代碼

本節說明這項政策觸發錯誤時設定的錯誤訊息和流程變數。如果您正在開發 Proxy 的錯誤規則，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

錯誤代碼前置字串

不適用

執行階段錯誤

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

部署錯誤

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

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

錯誤變數

不適用

錯誤回應範例

不適用