API 管理快取原則

本文提供下列 API 管理原則的參考。 如需有關新增和設定原則的資訊,請參閱 API 管理中的原則

重要

內建快取是暫時性的,而且在相同的 API 管理服務中,相同區域中的所有單位都會共用這些快取。

快取原則

從快取取得

使用 cache-lookup 原則來執行快取查閱並傳回有效的快取回應 (如果有的話)。 此原則可於回應內容在一段期間維持靜態時套用。 回應快取可降低加諸於後端 Web 伺服器的頻寬和處理需求,並縮短 API 取用者所感受的延遲時間。

注意

此原則必須有對應的儲存至快取原則。

原則陳述式

<cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" caching-type="prefer-external | external | internal" downstream-caching-type="none | private | public" must-revalidate="true | false" allow-private-response-caching="@(expression to evaluate)">
  <vary-by-header>Accept</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Accept-Charset</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Authorization</vary-by-header>
  <!-- should be present when allow-private-response-caching is "true"-->
  <vary-by-header>header name</vary-by-header>
  <!-- optional, can repeated several times -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can repeated several times -->
</cache-lookup>

注意

使用時 vary-by-query-parameter ,您可能會想要宣告重寫 uri 範本中的參數,或將屬性設 copy-unmatched-paramsfalse 。 停用此旗標,未宣告的參數會傳送至後端。

範例

範例

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="true" caching-type="internal" >
            <vary-by-query-parameter>version</vary-by-query-parameter>
        </cache-lookup>
    </inbound>
    <outbound>
        <cache-store duration="seconds" />
        <base />
    </outbound>
</policies>

使用原則運算式的範例

此範例說明如何設定 API 管理回應快取期間,使其符合備用服務之 Cache-Control 指示詞所指定的後端服務回應快取。 如需設定和使用此原則的示範,請觀賞 Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky,快轉到 25:25。

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

如需詳細資訊,請參閱原則運算式內容變數

項目

名稱 描述 必要
cache-lookup 根元素。
vary-by-header 根據指定標頭 (例如 Accept、Accept-Charset、Accept-Encoding、Accept-Language、Authorization、Expect、From、Host、If-Match) 的值開始快取回應。
vary-by-query-parameter 根據指定查詢參數的值開始快取回應。 輸入單一或多個參數。 使用分號作為分隔符號。 如果未指定任何參數,則會使用所有查詢參數。

屬性

名稱 描述 必要 Default
allow-private-response-caching 當設定為 true 時,可快取包含 Authorization 標頭的要求。 false
快取類型 選擇下列屬性值:
- internal,使用內建 API 管理快取,
- external,使用外部快取,如在 Azure API 管理中使用外部 Azure Redis 快取中所述,
- prefer-external。如有設定,則使用外部快取;否則使用內部快取。
prefer-external
downstream-caching-type 此屬性必須設為下列其中一個值。

- none - 不允許下游快取。
- private - 允許下游私人快取。
- public - 允許私人和共用下游快取。
must-revalidate 當下游快取啟用時,此屬性會開啟或關閉閘道回應中的 must-revalidate 快取控制指示詞。 true
vary-by-developer true 為,則會將每個開發人員帳戶的回應快取到要求中所包含的 用帳戶金鑰。 False
vary-by-developer-groups 設定為 true 可按照使用者群組來快取回應。 False

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ inbound
  • 原則範圍: 所有範圍

儲存至快取

cache-store 原則會根據指定的快取設定來快取回應。 此原則可於回應內容在一段期間維持靜態時套用。 回應快取可降低加諸於後端 Web 伺服器的頻寬和處理需求,並縮短 API 取用者所感受的延遲時間。

注意

此原則必須有對應的從快取中取得原則。

原則陳述式

<cache-store duration="seconds" cache-response="true | false" />

範例

範例

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" downstream-caching-type="none | private | public" must-revalidate="true | false">
            <vary-by-query-parameter>parameter name</vary-by-query-parameter> <!-- optional, can repeated several times -->
        </cache-lookup>
    </inbound>
    <outbound>
        <base />
        <cache-store duration="3600" />
    </outbound>
</policies>

使用原則運算式的範例

此範例說明如何設定 API 管理回應快取期間,使其符合備用服務之 Cache-Control 指示詞所指定的後端服務回應快取。 如需設定和使用此原則的示範,請觀賞 Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky,快轉到 25:25。

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

如需詳細資訊,請參閱原則運算式內容變數

項目

名稱 描述 必要
cache-store 根元素。

屬性

名稱 描述 必要 Default
duration 快取項目的存留時間,以秒為單位進行指定。 N/A
快取-回應 設定為 true 可快取目前的 HTTP 回應。 如果省略此屬性或將其設定為 false,則只會快取具有狀態碼的 HTTP 回應 200 OK false

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸出
  • 原則範圍: 所有範圍

從快取取得值

使用 cache-lookup-value 原則以執行依索引鍵的快取查閱,並傳回快取的值。 金鑰可以具有任意字串值,而且通常會使用原則運算式來提供。

注意

此原則必須有對應的儲存快取中的值原則。

原則陳述式

<cache-lookup-value key="cache key value"
    default-value="value to use if cache lookup resulted in a miss"
    variable-name="name of a variable looked up value is assigned to"
    caching-type="prefer-external | external | internal" />

範例

如需此原則的詳細資訊和範例,請參閱在 Azure API 管理中自訂快取

<cache-lookup-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    variable-name="userprofile" />

項目

名稱 描述 必要
cache-lookup-value 根元素。

屬性

名稱 描述 必要 Default
快取類型 選擇下列屬性值:
- internal,使用內建 API 管理快取,
- external,使用外部快取,如在 Azure API 管理中使用外部 Azure Redis 快取中所述,
- prefer-external。如有設定,則使用外部快取;否則使用內部快取。
prefer-external
default-value 當快取索引鍵查閱沒有結果時,要指派給變數的值。 如果未指定此屬性,則會指派 null null
索引鍵 要在查閱中使用的快取索引鍵值。 N/A
variable-name 查閱成功時,要將查閱到的值指派到之內容變數的名稱。 如果查閱結果遺漏,將不會設定變數。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤
  • 原則範圍: 所有範圍

儲存快取中的值

cache-store-value 會依索引鍵執行快取儲存。 金鑰可以具有任意字串值,而且通常會使用原則運算式來提供。

注意

在此原則執行的快取中儲存值的作業是非同步。 您可以使用快取原則的 Get 值 來抓取儲存的值。 不過,預存值可能無法立即供抓取,因為在快取中儲存值的非同步作業仍在進行中。

原則陳述式

<cache-store-value key="cache key value" value="value to cache" duration="seconds" caching-type="prefer-external | external | internal" />

範例

如需此原則的詳細資訊和範例,請參閱在 Azure API 管理中自訂快取

<cache-store-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    value="@((string)context.Variables["userprofile"])" duration="100000" />

項目

名稱 描述 必要
cache-store-value 根元素。

屬性

名稱 描述 必要 Default
快取類型 選擇下列屬性值:
- internal,使用內建 API 管理快取,
- external,使用外部快取,如在 Azure API 管理中使用外部 Azure Redis 快取中所述,
- prefer-external。如有設定,則使用外部快取;否則使用內部快取。
prefer-external
duration 會針對所提供的持續時間值來快取值,以秒為單位進行指定。 N/A
索引鍵 用來做為值儲存依據的快取索引鍵。 N/A
要快取的值。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤
  • 原則範圍: 所有範圍

移除快取中的值

cache-remove-value 會刪除依其索引鍵所識別的快取項目。 金鑰可以具有任意字串值,而且通常會使用原則運算式來提供。

原則陳述式


<cache-remove-value key="cache key value" caching-type="prefer-external | external | internal"  />

範例


<cache-remove-value key="@("userprofile-" + context.Variables["enduserid"])"/>

項目

名稱 描述 必要
cache-remove-value 根元素。

屬性

名稱 描述 必要 Default
快取類型 選擇下列屬性值:
- internal,使用內建 API 管理快取,
- external,使用外部快取,如在 Azure API 管理中使用外部 Azure Redis 快取中所述,
- prefer-external。如有設定,則使用外部快取;否則使用內部快取。
prefer-external
索引鍵 要從快取中移除之先前快取值的索引鍵。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤
  • 原則範圍: 所有範圍

下一步

如需使用原則的詳細資訊,請參閱︰