LookupCache 政策

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

查看 Apigee Edge 說明文件。

政策圖示

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

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

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

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

元素參考資料

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

<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 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
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>

預設值：

「Exclusive」

外觀狀態：

 選用

類型：

字串

<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 代理伺服器部署在名為「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 政策中定義的快取行為後，即可使用下列預先定義的 Flow 變數。

變數 類型 權限 說明
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 代理程式就會部署失敗。
CacheNotFound 如果未在特定的 Message Processor 元件上建立錯誤訊息中提及的特定快取，就會發生這個錯誤。

錯誤變數

不適用

錯誤回應範例

不適用