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>

示例

示例

<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(Cloud Cover 第 177 集:Vlad Vinogradsky 讲述更多 API 管理功能),快进到 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 根据指定查询参数的值开始缓存响应。 请输入一个或多个参数。 使用分号作为分隔符。 如果未指定任何参数,将使用所有查询参数。

属性

名称 说明 必须 默认
allow-private-response-caching 设置为 true 即可缓存包含 Authorization 标头的请求。 false
caching-type 在以下属性值之间进行选择:
- internal 使用内置的 API 管理缓存;
- external 使用外部缓存;
- prefer-external 如果外部缓存已配置,则使用外部缓存,否则使用内部缓存。
prefer-external
downstream-caching-type 此属性必须设置为以下值之一。

- none - 不允许下游缓存。
- private - 允许下游专用缓存。
- public - 允许专用和共享下游缓存。
must-revalidate 启用下游缓存时,此属性会启用或关闭网关响应中的 must-revalidate 缓存控制指令。
vary-by-developer 设置为 true 以缓存每个开发人员帐户的响应,这些帐户具有请求中包含的订阅密钥 False
vary-by-developer-groups 设置为 true 即可按用户组缓存响应。 False

使用情况

此策略可在以下策略范围中使用。

  • 策略节: 入站
  • 策略范围: 所有范围

存储到缓存

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(Cloud Cover 第 177 集:Vlad Vinogradsky 讲述更多 API 管理功能),快进到 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 根元素。

属性

名称 说明 必须 默认
duration 缓存条目的生存时间,以秒为单位指定。 空值
cache-response 设置为 true 可缓存当前 HTTP 响应。 如果省略此属性或将其设置为 false,则只缓存状态代码为 200 OK 的 HTTP 响应。 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 根元素。

属性

名称 说明 必须 默认
caching-type 在以下属性值之间进行选择:
- internal 使用内置的 API 管理缓存;
- external 使用外部缓存;
- prefer-external 如果外部缓存已配置,则使用外部缓存,否则使用内部缓存。
prefer-external
default-value 在缓存密钥查找未命中的情况下,会分配给变量的值。 如果未指定此属性,则会分 null null
key 要在查找中使用的缓存密钥值。 不适用
variable-name 在查找成功的情况下,会向其分配查找值的上下文变量的名称。 如果查找未命中,则不会设置该变量。 空值

使用情况

此策略可在以下策略范围中使用。

  • 策略节: 入站、出站、后端、错误时
  • 策略范围: 所有范围

在缓存中存储值

cache-store-value 按密钥执行缓存存储。 密钥的值可以是任意字符串,通常使用策略表达式来提供密钥。

备注

此策略将值存储到缓存中这项操作是异步执行的。 可以使用从缓存获取值策略检索存储的值。 但是,存储的值可能不会立即就能检索,因为将值存储到缓存中的异步操作可能仍在进行中。

策略语句

<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 根元素。

属性

名称 说明 必须 默认
caching-type 在以下属性值之间进行选择:
- internal 使用内置的 API 管理缓存;
- external 使用外部缓存;
- prefer-external 如果外部缓存已配置,则使用外部缓存,否则使用内部缓存。
prefer-external
duration 会根据提供的期间值(以秒为单位指定)将值缓存一段时间。 不适用
key 缓存密钥,会在其下存储值。 空值
value 要缓存的值。 空值

使用情况

此策略可在以下策略范围中使用。

  • 策略节: 入站、出站、后端、错误时
  • 策略范围: 所有范围

从缓存中删除值

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 根元素。

属性

名称 说明 必须 默认
caching-type 在以下属性值之间进行选择:
- internal 使用内置的 API 管理缓存;
- external 使用外部缓存;
- prefer-external 如果外部缓存已配置,则使用外部缓存,否则使用内部缓存。
prefer-external
key 以前所缓存的值(将从缓存中删除)的密钥。 空值

使用情况

此策略可在以下策略范围中使用。

  • 策略节: 入站、出站、后端、错误时
  • 策略范围: 所有范围

后续步骤

有关如何使用策略的详细信息,请参阅: