InvalidateCache 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

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

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

如需快取後端資源的回應,請參閱回應快取政策

元素參照

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

<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 Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

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

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

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

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<CacheContext>/<APIProxyName> 元素

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

<APIProxyName>application_that_added_the_entry</APIProxyName>

屬性

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

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

請將 <CacheKey> 元素與 <Prefix><Scope> 搭配使用。詳情請參閱「使用快取金鑰」。

<CacheResource> 元素

指定訊息應儲存的快取。

如果這項政策 (以及相應的 PopulateCache 和 LookupCache 政策) 使用隨附的共用快取,則完全省略此元素。

<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> 搭配使用。詳情請參閱「使用快取金鑰」。

<CacheContext>/<ProxyName> 元素

指定快取資料的 Proxy 名稱。

<ProxyName>proxy_for_which_data_was_cached</ProxyName>

預設:

不適用

所在地:

選用

類型:

字串

屬性

屬性 說明 預設 存在必要性 類型
參考資料 要取得這個值的變數。如果這個元素包含常值,請勿使用。 不適用 選用 字串

<PurgeChildEntries> 元素

true:清除與這項政策設定的 <KeyFragment> 元素共用值的快取項目。快取金鑰其他部分的值 (例如 <Prefix> 元素中的值) 不會列入考慮。

請注意,必須指定 <KeyFragment> 元素。否則,為 <PurgeChildEntries> 設定 True 可能會導致系統清除快取中的所有項目。

如要一次清除多個相關項目,請撤銷同一個鍵片段值的所有快取項目。

<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>

預設:

false

所在地:

選用

類型:

布林值

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設:

「獨家」

所在地:

選用

類型:

字串

<Scope> 設定會決定根據 <Scope> 值前面加上的快取金鑰。例如,當範圍設為 Exclusive 時,快取金鑰會採用以下形式:

orgName__envName__applicationName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]。

如果 <CacheKey> 中有 <Prefix> 元素,該元素會取代 <Scope> 元素值。有效值包含下列列舉。

請將 <Scope> 元素與 <CacheKey><Prefix> 搭配使用。詳情請參閱「使用快取金鑰」。

可接受的值

範圍值 說明
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

前方的快取金鑰,格式為 orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName

例如,整個字串可能如下所示:

apifactory__test__weatherapi__16__default__apiAccessToken

<CacheContext>/<TargetName> 元素

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

<TargetName>endpoint_for_which_data_was_cached</TargetName>

預設:

不適用

所在地:

選用

類型:

字串

屬性

屬性 說明 預設 存在必要性 類型
參考資料 要取得這個值的變數。如果這個元素包含常值,請勿使用。 不適用 選用 字串

使用須知

依據填入快取政策LookupCache 政策和 InvalidateCache 政策的一般用途快取,系統會使用您設定的快取,或是預設包含的共用快取。在大多數情況下,基本的共用快取應可滿足您的需求。如要使用這個快取,只要省略 <CacheResource> 元素即可。

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

錯誤代碼

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

錯誤代碼前置字串

不適用

執行階段錯誤

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

部署錯誤

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

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

錯誤變數

不適用

錯誤回應範例

不適用