LookupCache 政策

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

設定如何在執行階段擷取快取值。

這項政策適用於一般用途的短期快取。這項功能會與填入快取政策 (用於寫入項目) 和撤銷快取政策 (適用於無效項目) 搭配使用。

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

元素參照

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

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

根據預設，系統會納入共用快取。如要使用共用快取，請略過這項政策設定中的 <CacheResource> 元素。

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

<LookupCache> 屬性

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

屬性 說明 預設 存在必要性
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 屬性值。
存在必要性 選填
類型 字串

<AssignTo> 元素

指定從快取中擷取快取項目後為其指派的變數。變數必須可寫入。如果快取查詢未擷取值，系統就不會設定變數。

<AssignTo>variable_to_receive_cached_value</AssignTo>

預設值：

無

所在地：

 必要

類型：

字串

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

<CacheLookupTimeoutInSeconds> 元素

{/1}

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

預設值：

30

所在地：

 選填

類型：

整數

<CacheResource> 元素

指定儲存訊息的快取。

如果這項政策 (以及相應的 PopulateCache 和 InvalidateCache 政策) 使用隨附的共用快取，請完全略過這項元素。

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

屬性

屬性 類型 預設 必要 說明
ref 字串 否

要取得值的變數。如果此元素包含常值，請勿使用。

<CacheKey>/<Prefix> 元素

指定要當做快取金鑰前置字串使用的值。

<Prefix>prefix_string</Prefix>

預設值：

無

所在地：

 選填

類型：

字串

如要自行指定值 (而非 <Scope> 列舉值)，請使用這個值取代 <Scope>。如已定義，<Prefix> 會寫入寫入快取項目的快取金鑰值。<Prefix> 元素值會覆寫 <Scope> 元素值。

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

<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，後面加上存取權杖的序列化值。針對部署在「apifactory」機構中名為「test」的環境中的 API Proxy，系統會將存取權杖儲存在以下快取金鑰：apifactory__test__apiAccessToken。
Application

使用 API Proxy 名稱做為前置字串。

快取金鑰的格式為 orgName__envName__<應用程式>名稱。
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
。

使用須知

這項政策可用於一般用途的快取。在執行階段，LookupCache 政策會從快取中擷取一個值，將值指派給使用 AssignTo 元素指定的變數 (如未擷取任何值，系統就不會設定變數)。這個值是根據透過 CacheKey 和 Scope 元素 (由設定而建立的) 來建立的值。換句話說，如要擷取 PopulateCache 政策新增至快取的特定值，您的 LookupCache 政策必須以與 PopulateCache 政策相同的方式設定快取金鑰相關元素。

透過人口快取政策、LookupCache 政策和 InvalidateCache 政策執行一般用途快取時，系統會使用您設定的快取或預設加入的快取。在大多數情況下，基礎共用快取應能滿足您的需求。如要使用預設快取，只要省略 <CacheResource> 元素即可。

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

流程變數

流程 HTTP 標頭或訊息內容，以及流程可用的結構定義，可用於設定政策和流程的動態執行階段行為。如要進一步瞭解資料流變數，請參閱「變數參考資料」。

自訂您在 LookupCache 政策中定義的快取行為後，即可使用下列預先定義的流程變數。

Variables 類型 權限 說明
lookupcache.{policy-name}.cachename 字串 唯讀 傳回政策中使用的快取名稱。
lookupcache.{policy-name}.cachekey 字串 唯讀 傳回使用的金鑰。
lookupcache.{policy-name}.cachehit 布林值 唯讀 如果政策找到指定快取金鑰的值，則為 True。
lookupcache.{policy-name}.assignto 字串 唯讀 傳回指派快取的變數。

錯誤代碼

本節說明這項政策觸發錯誤時設定的錯誤訊息和流程變數。這項資訊有助瞭解您是否需要為 Proxy 建立錯誤規則。詳情請參閱「政策錯誤相關須知」和「處理錯誤」這兩篇文章。

錯誤代碼前置字串

無

執行階段錯誤

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

部署錯誤

當您部署包含此政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidCacheResourceReference 如果 <CacheResource> 元素設為名稱，在部署 API Proxy 的環境中不存在，就會發生這個錯誤。
InvalidTimeout 如果 <CacheLookupTimeoutInSeconds> 元素設為負值，則 API Proxy 部署作業失敗。
CacheNotFound 如果錯誤訊息中提及的特定快取並未建立特定訊息處理工具元件，就會發生這個錯誤。

錯誤變數

無

錯誤回應示例

無