從快取中取得

  • 發行項

適用於：所有 API 管理 層

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

注意

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

重要

內建快取具揮發性，且相同區域的所有單位共用相同的 API 管理服務。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 為了協助您設定此原則，入口網站會提供引導式表單型編輯器。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<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 be repeated -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can be repeated -->
</cache-lookup>

屬性

屬性 描述 是必要欄位 預設
allow-private-response-caching 當設定為 true 時，可快取包含 Authorization 標頭的要求。 允許使用原則運算式。 No false
caching-type 選擇下列屬性值：
- internal，使用內建的 APIM 快取，
- external，使用外部快取，如在 Azure API 管理中使用外部 Azure Redis 快取中所述，
- prefer-external。如有設定，則使用外部快取；否則使用內部快取。

不允許使用原則運算式。		 No prefer-external
downstream-caching-type 此屬性必須設為下列其中一個值。

- none - 不允許下游快取。
- 私人 - 允許下游私人快取。
- 公用 - 允許私人和共用下游快取。

允許使用原則運算式。		 No none
must-revalidate 當啟用下游快取時，此屬性會開啟或關閉閘道回應中的must-revalidate快取控制指示詞。 允許使用原則運算式。 No true
vary-by-developer 設定為true，以快取每個擁有要求內含開發人員訂閱金鑰的帳戶回應。 允許使用原則運算式。 Yes false
vary-by-developer-groups 設定為 true 可按照使用者群組來快取回應。 允許使用原則運算式。 Yes false

元素

名稱 描述 必要
vary-by-header 新增一或多個這類元素，以根據指定標頭的每個值開始快取回應，例如 Accept、Accept-Charset、Accept-Encoding、Accept-Language、Authorization、Expect、From、Host、If-Match。 No
vary-by-query-parameter 新增一或多個這類元素，以根據指定查詢參數的每個值開始快取回應。 輸入單一或多個參數。 使用分號作為分隔符號。 No

使用方式

使用注意事項

  • APIM 只會針對 HTTP GET 要求執行快取查閱。
  • 使用 vary-by-query-parameter 時，您可能會想要在 rewrite-uri 範本中宣告參數，或將屬性 copy-unmatched-params 設定為 false。 藉由停用此旗標，將未宣告的參數傳送至後端。
  • 此原則只能在原則區段中使用一次。

範例

對應 cache-store 原則的範例

<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 指示詞所指定的後端服務回應快取。

<!-- 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;
  }"
 />

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

相關內容

如需使用原則的詳細資訊，請參閱：