ResponseCache 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

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

如要進行一般用途的短期快取，建議使用「填入快取」政策。 這項政策會與「Lookup Cache」政策 (用於讀取快取項目) 和「Invalidate Cache」政策 (用於撤銷項目) 搭配使用。

觀看這部影片，瞭解回應快取政策簡介。

範例

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 政策。請注意，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> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

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

預設值：

N/A

外觀狀態：

 必填

類型：

N/A

<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。詳情請參閱「快取」。

<CacheResource>cache_to_use</CacheResource>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

如要進一步瞭解如何設定快取，請參閱「建立及編輯環境快取」。

<CacheKey> 元素

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

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

預設值：

N/A

外觀狀態：

 選用

類型：

N/A

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

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

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

屬性

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

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

<CacheKey>/<Prefix> 元素

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

<Prefix>prefix_string</Prefix>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

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

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

<ExcludeErrorResponse> 元素

目前這項政策預設會快取具有任何可能狀態碼的 HTTP 回應。也就是說，成功和錯誤回應都會快取。舉例來說，預設會快取狀態碼為 2xx 和 3xx 的回應。

如果不想快取 HTTP 錯誤狀態碼的目標回應，請將這個元素設為 true；如果這個元素為 true，系統只會快取狀態碼介於 200 到 205 的回應。Edge 只會將這些 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>

預設值：

N/A

外觀狀態：

 必填

類型：

N/A

<ExpirySettings>/<ExpiryDate> 元素

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

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

預設值：

N/A

外觀狀態：

 選用

類型：

字串

屬性

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

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

 N/A 選用 字串

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

預設值：

 N/A

外觀狀態：

 選用

類型：

字串

屬性

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

<ExpirySettings> 元素/<TimeoutInSec> 元素

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

<ExpirySettings>/<TimeoutInSeconds> 元素

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

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

注意：如果參照未從 duration_variable 收到值，請提供要使用的預設逾時值。

預設值：

N/A

外觀狀態：

 選用

類型：

字串

屬性

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

<Scope> 元素

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

<Scope>scope_enumeration</Scope>

預設值：

「Exclusive」

外觀狀態：

 選用

類型：

字串

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

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

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

ProxyEndpoint 設定會做為前置字串。

快取金鑰會以 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName 格式預先附加。
Target

TargetEndpoint 設定會做為前置字串。

快取鍵會以 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName 格式預先附加。
Exclusive

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

前置字元有兩種形式：

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

快取金鑰會以以下格式加上前置字串：orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

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

apifactory__test__weatherapi__16__default__apiAccessToken
。

<SkipCacheLookup> 元素

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

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

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

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

<SkipCachePopulation> 元素

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

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

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

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

<UseAcceptHeader> 元素

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

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

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

詳情請參閱「設定快取金鑰」一節。

<UseAcceptHeader>false</UseAcceptHeader>

預設值：

false

外觀狀態：

 選用

類型：

布林值

<UseResponseCacheHeaders> 元素

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

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

預設值：

false

外觀狀態：

 選用

類型：

布林值

使用須知

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

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

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

設定快取項目到期時間

與 Populate Cache policy 相同，您可以使用 <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 標頭附加至鍵值，讓快取金鑰更有意義。

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

關於快取加密

公有雲專用 Edge：快取內容僅會在啟用 PCI 和 HIPAA 的機構中加密。系統會在機構佈建期間設定這些機構的加密功能。

流程變數

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

變數 類型 權限 說明
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 如果尚未在特定的訊息處理器元件上建立錯誤訊息中提及的特定快取，就會發生這個錯誤。

錯誤變數

不適用

錯誤回應範例

不適用

結構定義

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