LookupCache 政策

可擴充的政策

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

查看 Apigee Edge 說明文件。

LookupCache 政策會設定在執行階段擷取快取值的方式。

這項政策適用於一般用途的短期快取。這項政策會與 PopulateCache 政策 (用於寫入項目) 和 InvalidateCache 政策 (用於使項目失效) 一併使用。

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

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

元素參考資料

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

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <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 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

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

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

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

<CacheLookupTimeoutInSeconds> 元素

指定在快取查詢失敗後，經過多少秒會視為快取未命中。如果發生這種情況，流程會沿著快取未命中路徑繼續執行。

<CacheLookupTimeoutInSeconds>12</CacheLookupTimeoutInSeconds>

預設值：

12

外觀狀態：

 選用

類型：

整數

<CacheResource> 元素

指定訊息的儲存快取。

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

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

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設值：

「專屬」

外觀狀態：

 選用

類型：

字串

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

如果 <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__proxyEndpointName」格式加在前面。
Target

TargetEndpoint 設定會做為前置字串。

快取金鑰會以 orgName__envName__applicationName__targetEndpointName 格式預先附加。
Exclusive

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

前置字元有兩種形式：

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

快取鍵前置字串的格式為 orgName__envName__applicationName__proxyNameITargetName

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

apifactory__test__weatherapi__default__apiAccessToken
。

使用須知

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

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

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

流程變數

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

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

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

錯誤代碼

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.

Error name Cause Fix
InvalidCacheResourceReference This error occurs if the <CacheResource> element is set to a name which does not exist in the environment where the API proxy is being deployed.
InvalidTimeout If the <CacheLookupTimeoutInSeconds> element is set to a negative number, then the deployment of the API proxy fails.
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