從快取取得

  • 發行項

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

注意

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

重要

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

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 為了協助您設定此原則，入口網站會提供引導式與基於表單的編輯器。 深入了解如何設定或編輯 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 be repeated -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can be repeated -->
</cache-lookup>

屬性

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

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

項目

名稱 描述 必要
vary-by-header 新增一或多個這些元素，以開始每個指定標頭值的快取回應，例如 Accept 、 Accept-Charset 、 AuthorizationFromAccept-LanguageExpectAccept-Encoding 、 。 HostIf-Match 否
vary-by-query-parameter 新增其中一或多個元素，以根據指定的查詢參數值開始快取回應。 輸入單一或多個參數。 使用分號作為分隔符號。 如果未指定任何參數，則會使用所有查詢參數。 否

使用方式

使用注意事項

使用 vary-by-query-parameter 時，您可能會想要在 rewrite-uri 範本中宣告參數，或將屬性 copy-unmatched-params 設定為 false。 藉由停用此旗標，不會宣告的參數會傳送至後端。

範例

具有對應快取存放區原則的範例

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

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

後續步驟

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