ResponseCache 政策

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

快取後端資源中的資料，減少傳送至資源的要求數量。應用程式向相同的 URI 發出要求時，您可以使用這項政策傳回快取回應，而不是將這些要求轉送至後端伺服器。ResponseCache 政策可減少延遲時間和網路流量，藉此提升 API 的效能。

當您的 API 使用的後端資料會定期更新時，ResponseCache 可能最為實用。舉例來說，假設您有一個 API 公開天氣報告資料，且資料每十分鐘更新一次。您可以運用 ResponseCache 在重新整理之間傳回快取回應，藉此減少到達後端的要求數量。這樣也能減少網路躍點數量。

如果是一般用途的短期快取，請考慮使用填入快取政策。 這項政策會與查詢快取政策 (用於讀取快取項目) 和撤銷快取政策 (用於撤銷項目) 搭配使用。

請觀看這部簡介「回應快取」政策。

範例

10 分鐘快取

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

假設您在以下網址有 API：

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

您目前使用查詢參數 w 做為快取金鑰。Apigee Edge 會在收到要求時檢查查詢參數 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 政策。請注意，略過快取條件會設為 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 Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

 不適用 需要
continueOnError

如果設為 false，即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true，即可在政策失敗後繼續執行資料流。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用這項政策。即使政策仍附加在流程中，系統也不會強制執行政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性外，您還可以使用不同的自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

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

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

<CacheLookupTimeoutInSeconds> 元素

指定超過幾秒後，系統會將失敗的快取查詢視為快取失敗。如果發生這種情況，資料流會在快取錯誤的路徑中恢復。

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

預設：

30

所在地：

 選用

類型：

整數

<CacheResource> 元素

指定訊息應儲存的快取。省略這個元素即可使用隨附的共用快取。如果您希望能管理明確清除快取中包含的項目，請使用名稱指定 CacheResource。詳情請參閱「快取」。

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

屬性

屬性 類型 預設 必要 說明
參考資料 字串 否

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

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

預設：

不適用

所在地：

 選用

類型：

字串

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

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

<ExcludeErrorResponse> 元素

根據預設，這項政策會使用「任何」可能的狀態碼來快取 HTTP 回應。這表示系統會快取成功和錯誤回應。舉例來說，根據預設，系統會快取含有 2xx 和 3xx 狀態碼的回應。

如果您「不想」快取含有 HTTP 錯誤狀態碼的目標回應，請將這個元素設為 true；只有在此元素為 true 時，系統才會快取狀態碼為 200 至 205 的回應。只有這些 HTTP 狀態碼會計為「成功」代碼，而且您無法變更這項關聯。

有關實用回應快取模式的討論，請參閱這篇社群文章。

注意：在日後推出的版本中 (決定確認) 會將這個元素的預設設定變更為 true。詳情請參閱 Apigee 版本資訊。

<ExcludeErrorResponse>true</ExcludeErrorResponse>

預設：

false

所在地：

 選用

類型：

布林值

<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="" />
屬性 說明 預設 存在必要性 類型
參考資料

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

 不適用 選用 字串

<ExpirySettings>/<TimeOfDay> 元素

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

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

時段的預設語言代碼和時區會因程式碼執行位置而異 (在設定政策時無法得知這項資訊)。如需設定語言代碼的相關資訊，請參閱「建立及編輯環境快取」。

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

預設：

 不適用

所在地：

 選用

類型：

字串

屬性

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

<ExpirySettings>/<TimeoutInSec> 元素

快取項目到期後的秒數。

<ExpirySettings>/<TimeoutInSeconds> 元素

快取項目到期後的秒數。這個標記存在時，此元素會覆寫其同層的 <TimeOfDay> 和 <ExpiryDate>。

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

注意：請提供預設逾時值，以便在參照未收到 duration_variable 的值時使用。

預設：

不適用

所在地：

 選用

類型：

字串

屬性

屬性 說明 預設 存在必要性 類型
參考資料 有逾時值的變數。
無
選用 字串

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設：

「獨家」

所在地：

 選用

類型：

字串

<Scope> 設定會決定根據 <Scope> 值前面加上的快取金鑰。舉例來說，當範圍設為 Exclusive 時，快取金鑰會呈現以下形式：orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [serializedCacheKey]。

如果 <CacheKey> 中有 <Prefix> 元素，該元素會取代 <Scope> 元素值。有效值包含下列列舉。

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

可接受的值

範圍值 說明
Global

快取金鑰會由環境部署的所有 API Proxy 共用。快取金鑰的前面會加上 orgName __ envName __ 的格式。

如果您使用 <KeyFragment> apiAccessToken 和 <Global> 範圍定義 <CacheKey> 項目，每個項目都會儲存為 orgName__envName__apiAccessToken，後面接著存取權杖的序列化值。如果 API Proxy 部署在名為「apifactory」的機構中，即部署在「test」的環境中，存取權杖會儲存在下列快取金鑰底下：apifactory__test__apiAccessToken。
Application

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

快取金鑰的前面會加上 orgName__envName__apiProxyName，
Proxy

系統會使用 ProxyEndpoint 設定做為前置字串。

快取金鑰的前面會加上 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName。
Target

TargetEndpoint 設定會做為前置字串使用。

前置的快取金鑰，格式為 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName。
Exclusive

預設。這是最具體的做法，因此在指定快取中會造成命名空間衝突的風險降到最低。

前置字串為下列其中一種格式：

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

前方的快取金鑰，格式為 orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

例如，整個字串可能如下所示：

apifactory__test__weatherapi__16__default__apiAccessToken
。

<SkipCacheLookup> 元素

定義在執行階段判定為 true 的運算式，會指定應略過快取查詢，並應重新整理快取。另請參閱這部影片，瞭解如何使用 SkipCacheLookup。

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

預設：

不適用

所在地：

 選用

類型：

字串

在以下範例中，如果傳入標頭中的略過-快取變數設為 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 標頭中的值。

計算快取金鑰時，邊緣會使用 Accept、Accept-Encoding、Accept-Language 和 Accept-Charset 要求標頭。這種做法可以防止用戶端取得未要求提供的媒體類型。

舉例來說，假設有兩個要求來自同一個網址，其中第一個要求接受 gzip，第二個要求則否。系統會快取第一個要求，而快取的項目 (可能) 會是 gzip 壓縮回應。第二個要求會讀取快取的值，接著可能會將 gzip 壓縮的項目傳回無法讀取 gzip 的用戶端。

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

<UseAcceptHeader>false</UseAcceptHeader>

預設：

false

所在地：

 選用

類型：

布林值

<UseResponseCacheHeaders> 元素

設為 true，讓系統在快取中設定回應的「存留時間」(TTL) 時將 HTTP 回應標頭納入考量。如果是這樣，Edge 會考量下列回應標頭的值，並在設定時間發布時比較 <ExpirySettings> 設定的值：

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

預設：

false

所在地：

 選用

類型：

布林值

使用須知

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

透過 ResponseCache 政策中的設定，您可以讓 Edge 包含 HTTP 回應標頭，藉此設定快取項目到期時間和快取金鑰。本節說明可以透過政策搭配標頭，管理快取到期時間和快取金鑰。

如要進一步瞭解 Edge 如何使用 ResponseCache 政策處理回應標頭，請參閱 HTTP 回應標頭支援功能。

設定快取項目到期時間

與填入快取政策相同，您可以使用 <ExpirySettings> 元素設定回應快取項目的到期時間 (生效時間)。在 ResponseCache 政策中，您也可以讓 Edge 考慮是否存在回應標頭。

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

例如，假設以下列值快取回應：

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

在這種情況下，Cache-Control max-age 值會用於存留時間，因為這個值低於 <ExpirySettings> 值，且沒有 Cache-Control s-maxage 值 (優先順序高於 max-age)。

設定快取金鑰

如同填入快取政策等一般用途的快取政策，您可以透過 ResponseCache 使用 <CacheKey> 和 <Scope> 元素設定快取項目的快取金鑰。使用 ResponseCache，您也可以讓金鑰值加上回應 Accept 標頭，讓快取金鑰更有意義。

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

關於快取加密

公有雲的邊緣：快取只會在啟用 PCI 和健康保險流通與責任法案的機構中加密。這些機構的加密作業會在機構佈建期間設定。

流程變數

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

變數 類型 權限 說明
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 提供政策結構定義。