ResponseCache 政策

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

查看 Apigee Edge 說明文件。

政策圖示

這項政策會快取後端資源的資料，減少對該資源的要求數量。由於應用程式會向相同 URI 發出要求，因此您可以運用這項政策傳回快取回應，不必將這些要求轉送至後端伺服器。ResponseCache 政策可減少延遲和網路流量，進而提升 API 效能。

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

如果 API 使用的後端資料只會定期更新，您可能會覺得 ResponseCache 最實用。舉例來說，假設您有一個 API 會公開天氣報告資料，但每十分鐘才會更新一次。使用 ResponseCache 在重新整理之間傳回快取的回應，即可減少傳送至後端的要求數量。這樣也能減少網路躍點數量。

如要進行一般用途的短期快取，建議使用 PopulateCache 政策。 這項政策會與 LookupCache 政策 (用於讀取快取項目) 和 InvalidateCache 政策 (用於使項目失效) 一併使用。

如需「回應快取」政策簡介，請觀看以下影片。

範例

10 分鐘快取

這個範例說明如何將快取回應保留 10 分鐘。

假設您在下列網址有 API：

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

您使用查詢參數 w 做為快取金鑰。每當收到要求時，Apigee 就會檢查查詢參數 w 的值。如果快取中存在有效 (即未過期) 的回應，系統會將快取的回應訊息傳回給要求用戶端。

現在假設您已設定 ResponseCache 政策，如下所示。

<ResponseCache name="ResponseCache">     <CacheKey>         <KeyFragment ref="request.queryparam.w" />     </CacheKey>     <ExpirySettings>         <TimeoutInSeconds>600</TimeoutInSeconds>     </ExpirySettings> </ResponseCache>

API Proxy 第一次收到下列網址的要求訊息時，會快取回應。在 10 分鐘內發出第二次要求時，系統會進行快取查詢，並將快取回應傳回應用程式，不會將要求轉送至後端服務。

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

略過快取查詢

以下範例說明如何略過快取查閱作業，並重新整理快取。另請參閱 這部影片，瞭解如何使用 SkipCacheLookup。

系統會在要求路徑中評估選用的 SkipCacheLookup 條件 (如有設定)。 如果條件評估結果為 true，系統就會略過快取查詢，並重新整理快取。

條件式快取重新整理的常見用途是定義特定 HTTP 標頭，導致條件評估結果為 true。您可以設定指令碼用戶端應用程式，定期提交含有適當 HTTP 標頭的要求，明確導致回應快取重新整理。

舉例來說，假設您要呼叫下列網址的 API：

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

現在，假設該 Proxy 已設定下列 ResponseCache 政策。請注意，bypass-cache 條件已設為 true。

<ResponseCache name="ResponseCache">     <CacheKey>         <KeyFragment ref="request.queryparam.w" />     </CacheKey>     <!-- Explicitly refresh the cached response -->     <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>     <ExpirySettings>         <TimeoutInSeconds>600</TimeoutInSeconds>     </ExpirySettings> </ResponseCache>

如要進一步瞭解條件，請參閱「流程變數和條件」。

元素參考資料

元素參照說明政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">     <DisplayName>Response Cache 1</DisplayName>     <Properties/>     <CacheKey>         <Prefix/>         <KeyFragment ref="request.uri" />     </CacheKey>     <Scope>Exclusive</Scope>     <ExpirySettings>         <ExpiryDate/>         <TimeOfDay/>         <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>     </ExpirySettings>     <CacheResource>cache_to_use</CacheResource>     <CacheLookupTimeoutInSeconds/>     <ExcludeErrorResponse/>     <SkipCacheLookup/>     <SkipCachePopulation/>     <UseAcceptHeader/>     <UseResponseCacheHeaders/> </ResponseCache>

<ResponseCache> 屬性

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

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

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

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

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

 false 選用
enabled

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

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

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

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

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

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<CacheKey> 元素

設定儲存在快取中的資料片段的專屬指標。

快取鍵的大小上限為 2 KB。

<CacheKey>     <Prefix>string</Prefix>     <KeyFragment ref="variable_name" />     <KeyFragment>literal_string</KeyFragment> </CacheKey>

預設值：

不適用

外觀狀態：

 必填

類型：

不適用

<CacheKey> 會建構儲存在快取中的每筆資料名稱。 通常會使用實體標頭或查詢參數中的值設定金鑰。在這種情況下，元素的 ref 屬性會指定含有鍵值的變數。

在執行階段，系統會在 <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>30</CacheLookupTimeoutInSeconds>

預設值：

30

外觀狀態：

 選用

類型：

整數

<CacheResource> 元素

指定要儲存郵件的快取。如要使用內含的共用快取，請省略這個元素。如要以管理員身分清除快取中的項目，請依名稱指定 CacheResource。詳情請參閱 Caches API。

<CacheResource>cache_to_use</CacheResource>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

<CacheKey> 元素

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

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

預設值：

不適用

外觀狀態：

 選用

類型：

不適用

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

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

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

屬性

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

要取得值的變數。如果這個元素含有字面值，則不應使用。

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

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

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

<ExcludeErrorResponse> 元素

這項政策可以快取任何狀態碼的 HTTP 回應。也就是說，成功和錯誤回應都可以快取，包括 2xx 和 3xx 狀態碼。

將這個元素設為 true (預設值)，即可排除錯誤回應。如果不希望排除含有 HTTP 錯誤狀態碼的快取目標回應，請將其設為 false。

如要瞭解這個元素適用的回應快取模式，請參閱「反模式簡介」。

<ExcludeErrorResponse>true</ExcludeErrorResponse>

預設值：

是

外觀狀態：

 選用

類型：

布林值

<ExpirySettings> 元素

指定快取項目的到期時間。如果存在，<TimeoutInSeconds> 會覆寫 <TimeOfDay> 和 <ExpiryDate>。

<ExpirySettings>   <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>   <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>   <ExpiryDate ref="date_variable">expiration_date</ExpiryDate> </ExpirySettings>

預設值：

不適用

外觀狀態：

 必填

類型：

不適用

<ExpirySettings>/<ExpiryDate> 元素

指定快取項目的到期日。請使用這份表單 mm-dd-yyyy。 如果存在，這個元素的同層級元素 <TimeoutInSeconds> 會覆寫 <ExpiryDate>。

<ExpirySettings>     <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate> </ExpirySettings>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

屬性

<ExpiryDate ref="" />
屬性 說明 預設 存在必要性 類型
ref

要取得值的變數。如果這個元素含有字面值，則不應使用。

 不適用 選用 字串

<ExpirySettings> 或 <TimeOfDay> 元素

快取項目的到期時間。請使用這份表單 hh:mm:ss。 如果存在，這個元素的同層級元素 <TimeoutInSeconds> 會覆寫 <TimeOfDay>。

以 HH:mm:ss 格式輸入時間，其中 HH 代表 24 小時制的小時。例如下午 2:30 為 14:30:00。

至於一天中的時間，預設語言代碼和時區會因程式碼的執行位置而異 (設定政策時無法得知)。

<ExpirySettings>     <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>

預設值：

 不適用

外觀狀態：

 選用

類型：

字串

屬性

屬性 說明 預設 存在必要性 類型
ref 含有到期時間值的變數。 不適用 選用 字串

<ExpirySettings>/<TimeoutInSec> 元素

快取項目應在幾秒後過期。

<ExpirySettings>/<TimeoutInSeconds> 元素

快取項目應在幾秒後過期。如果存在，這個元素會覆寫同層級的 <TimeOfDay> 和 <ExpiryDate>。

<ExpirySettings>     <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> </ExpirySettings>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

屬性

屬性 說明 預設 存在必要性 類型
ref 含有逾時值的變數。
不適用
選用 字串

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設值：

「Exclusive」

外觀狀態：

 選用

類型：

字串

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

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

您會搭配 <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__apiProxyName 格式預先附加。
Proxy

ProxyEndpoint 設定會做為前置字串。

快取金鑰會以「orgName__envName__apiProxyName__proxyEndpointName」orgName__envName__apiProxyName__proxyEndpointName格式加在開頭。
Target

TargetEndpoint 設定會做為前置字串。

快取金鑰會預先加上 orgName__envName__apiProxyName__targetEndpointName 格式。
Exclusive

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

前置字元有兩種形式：

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

快取金鑰會預先加上以下格式： orgName__envName__apiProxyName__proxyNameITargetName

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

apifactory__test__weatherapi__default__apiAccessToken
。

<SkipCacheLookup> 元素

定義運算式，如果運算式在執行階段評估為 true，則指定應略過快取查閱並重新整理快取。另請參閱使用 ResponseCache 政策影片，瞭解如何使用 SkipCacheLookup。

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

在下列範例中，如果傳入的標頭將 bypass-cache 變數設為 true，系統就會略過快取查詢並重新整理快取。

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

<SkipCachePopulation> 元素

定義運算式，如果運算式在執行階段評估為 true，則指定應略過寫入快取。另請參閱這部影片，瞭解如何使用 SkipCachePopulation。

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

預設值：

不適用

外觀狀態：

 選用

類型：

字串

舉例來說，如果回應狀態碼為 400 以上，下列程式碼會略過快取寫入作業：

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

<UseAcceptHeader> 元素

設為 true，即可在回應快取項目的快取鍵中附加回應 Accept 標頭的值。

Apigee 會在計算快取金鑰時使用 Accept、Accept-Encoding、Accept-Language 和 Accept-Charset 要求標頭。這種做法可避免用戶端取得未要求提供的媒體類型。

舉例來說，假設有兩項要求來自相同網址，第一項要求接受 gzip，第二項則不接受。第一個要求會快取，而快取的項目 (可能) 是經過 gzip 壓縮的回應。第二個要求會讀取快取值，然後可能會將經過 gzip 壓縮的項目傳回給無法讀取 gzip 的用戶端。

詳情請參閱設定快取金鑰。

<UseAcceptHeader>false</UseAcceptHeader>

預設值：

false

外觀狀態：

 選用

類型：

布林值

<UseResponseCacheHeaders> 元素

設為 true，即可在設定快取中回應的「存留時間」(TTL) 時，將 HTTP 回應標頭納入考量。如果為 true，Apigee 會考量下列回應標頭的值，並與設定存留時間時 <ExpirySettings> 設定的值進行比較：

  • Cache-Control s-maxage
  • Cache-Control max-age
  • Expires

詳情請參閱設定快取項目到期時間。

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

預設值：

false

外觀狀態：

 選用

類型：

布林值

使用須知

每個快取物件的大小上限為 256 KB。 (如要進一步瞭解 Apigee 如何處理快取，請參閱「快取內部機制」)。

您可以在 ResponseCache 政策中設定，讓 Apigee 在設定快取項目到期時間和快取金鑰時，加入 HTTP 回應標頭。本節說明如何使用附帶標題的政策，管理快取到期時間和快取金鑰。

如要進一步瞭解 Apigee 如何透過 ResponseCache 政策處理回應標頭，請參閱「支援 HTTP 回應標頭」。

設定快取項目到期時間

與 PopulateCache 政策相同，您可以使用 <ExpirySettings> 元素設定回應快取項目的到期時間 (存留時間)。在 ResponseCache 政策中，您也可以讓 Apigee 考慮回應標頭 (如有)。

如要使用回應標頭，請將 <UseResponseCacheHeaders> 元素值設為 true。這項設定會讓 Apigee 考量回應標頭，並與 <ExpirySettings> 設定的值進行比較，然後使用兩者之間的最低值。考量回應標頭時，Apigee 會選擇可用的值，如下所述：

圖表：顯示將 UseResponseCacheHeaders 設為 true 時會發生的情況。

舉例來說，假設快取的回應包含下列值：

  • 沒有 Cache-Control s-maxage 值
  • Cache-Control max-age 值為 300
  • 三天後的Expires日期
  • <ExpirySettings> TimeoutInSeconds 值為 600。

在本例中，系統會使用 Cache-Control max-age 值做為存留時間，因為該值低於 <ExpirySettings> 值，且沒有 Cache-Control s-maxage 值 (優先於 max-age)。

設定快取金鑰

與 PopulateCache 政策等一般用途的快取政策一樣，您可以使用 <CacheKey> 和 <Scope> 元素，為快取項目設定快取金鑰建立作業。您也可以使用 ResponseCache，將回應 Accept 標頭附加至鍵值，讓快取鍵更有意義。

如需設定快取金鑰的一般資訊，請參閱「使用快取金鑰」。如要瞭解如何使用 Accept 標頭，請參閱 <UseAcceptHeader>。

關於快取加密

Apigee 和 Apigee Hybrid (1.4 以上版本)：快取和 KVM 資料一律會加密。

流程變數

執行 ResponseCache 政策時，系統會填入下列預先定義的 Flow 變數。 如要進一步瞭解流程變數，請參閱「流程變數參考資料」。

變數 類型 權限 說明
responsecache.{policy_name}.cachename 字串 唯讀 傳回政策中使用的快取
responsecache.{policy_name}.cachekey 字串 唯讀 傳回使用的金鑰
responsecache.{policy_name}.cachehit 布林值 唯讀 政策執行成功時為 True
responsecache.{policy_name}.invalidentry 布林值 唯讀 如果快取項目無效，則為 True

錯誤代碼

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
InvalidTimeout If the <CacheLookupTimeoutInSeconds> element of the ResponseCache policy is set to a negative number, then the deployment of the API proxy fails.
InvalidCacheResourceReference This error occurs if the <CacheResource> element in a ResponseCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
ResponseCacheStepAttachmentNotAllowedReq This error occurs if the same ResponseCache policy is attached to multiple request paths within any flows of an API proxy.
ResponseCacheStepAttachmentNotAllowedResp This error occurs if the same ResponseCache policy is attached to multiple response paths within any flows of an API proxy.
InvalidMessagePatternForErrorCode This error occurs if either the <SkipCacheLookup> or the <SkipCachePopulation> element in a ResponseCache policy contains an invalid condition.
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

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。