本頁面由 Cloud Translation API 翻譯而成。

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

提示：收到要求時，系統會自動將 HTTP 標頭和查詢參數填入變數。任何 HTTP 標頭都可做為 request.header.{header_name} 使用，例如 request.header.user-agent。任何查詢參數都可做為 request.queryparam.{queryparam_name} 使用，例如 request.queryparam.action。

略過快取查詢

以下範例說明如何略過快取查閱作業，並重新整理快取。另請參閱這部影片，瞭解如何使用 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`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

如果省略這個元素，系統會使用政策的 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。

注意：如果這個元素設為 true，系統仍會快取 200 到 205 的狀態碼；這些是 Apigee 視為「成功」的 HTTP 狀態碼，您無法使用這個元素排除這些狀態碼。

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

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

注意：已淘汰。請使用 TimeoutInSeconds。如果同時存在 TimeoutInSec 和 TimeoutInSeconds 元素，Apigee 會使用 TimeoutInSeconds。

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

<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

錯誤代碼

本節將說明在政策觸發錯誤時，系統會設定的錯誤訊息和流程變數。如果您要為 Proxy 開發錯誤規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

錯誤代碼前置字串

不適用

執行階段錯誤

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

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因	修正
`InvalidTimeout`	如果 `ResponseCache` 政策的 `<CacheLookupTimeoutInSeconds>` 元素設為負數，API Proxy 的部署作業就會失敗。
`InvalidCacheResourceReference`	如果 `ResponseCache` 政策中的 `<CacheResource>` 元素設為在部署 API Proxy 的環境中不存在的名稱，就會發生這個錯誤。
`ResponseCacheStepAttachmentNotAllowedReq`	如果在 API Proxy 的任何流程中，將相同的 `ResponseCache` 政策附加至多個要求路徑，就會發生這個錯誤。
`ResponseCacheStepAttachmentNotAllowedResp`	如果在 API Proxy 的任何流程中，將相同的 `ResponseCache` 政策附加至多個回應路徑，就會發生這個錯誤。
`InvalidMessagePatternForErrorCode`	如果 `ResponseCache` 政策中的 `<SkipCacheLookup>` 或 `<SkipCachePopulation>` 元素含有無效條件，就會發生這個錯誤。
`CacheNotFound`	如果未在特定的 Message Processor 元件上建立錯誤訊息中提及的特定快取，就會發生這個錯誤。

錯誤變數

不適用

錯誤回應範例

不適用

結構定義

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

ResponseCache 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

範例

10 分鐘快取

略過快取查詢

元素參考資料

<ResponseCache> 屬性

<DisplayName> 元素

<CacheKey> 元素

<CacheLookupTimeoutInSeconds> 元素

<CacheResource> 元素

<CacheKey> 元素

屬性

<CacheKey>/<Prefix> 元素

<ExcludeErrorResponse> 元素

<ExpirySettings> 元素

<ExpirySettings>/<ExpiryDate> 元素

屬性

<ExpirySettings> 或 <TimeOfDay> 元素

屬性

<ExpirySettings>/<TimeoutInSec> 元素

<ExpirySettings>/<TimeoutInSeconds> 元素

屬性

<Scope> 元素

可接受的值

<SkipCacheLookup> 元素

<SkipCachePopulation> 元素

<UseAcceptHeader> 元素

<UseResponseCacheHeaders> 元素

使用須知

設定快取項目到期時間

設定快取金鑰

關於快取加密

流程變數

錯誤代碼

錯誤代碼前置字串

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

結構定義

ResponseCache 政策