你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

按密钥限制调用速率

适用于:开发人员 | 基本 | 基本 v2 | 标准 | 标准 v2 | 高级

rate-limit-by-key 策略可以对调用速率进行限制,使指定时段的调用不超出指定的数目,避免单个密钥的 API 使用量暴增。 密钥的值可以是任意字符串,通常使用策略表达式来提供密钥。 可以添加可选增量条件,指定在决定是否到达限制值时应该进行计数的请求。 超过此调用速率时,调用方会收到 429 Too Many Requests 响应状态代码。

若要了解速率限制和配额之间的差异,请参阅速率限制和配额

注意

由于限制体系结构的分布式性质,速率限制永远不可能完全准确。 允许的请求的配置数字和实际数字之间的差异因请求量和速度、后端延迟以及其他因素而异。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。 为了帮助你配置此策略,门户提供了基于窗体的引导式编辑器。 详细了解如何设置或编辑 API 管理策略

策略语句

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   increment-count="number"
                   counter-key="key value" 
                   retry-after-header-name="custom header name, replaces default 'Retry-After'" 
                   retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  
                   remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/> 

属性

属性 说明 需要 默认
calls renewal-period 所指定的时间间隔内键值的允许最大总调用数。 允许使用策略表达式。 不适用
counter-key 用于速率限制策略的密钥。 对于每个键值,单个计数器用于配置策略的所有范围。 允许使用策略表达式。 空值
increment-condition 一个布尔表达式,指定是否应将请求计入速率 (true)。 允许使用策略表达式。 空值
increment-count 每个请求增加计数器的数目。 允许使用策略表达式。 1
renewal-period 滑动窗口的长度(以秒为单位),在此期间,允许的请求数不应超过 calls 中指定的值。 允许的最大值:300 秒。 允许使用策略表达式。 空值
retry-after-header-name 自定义响应头的名称,其值为在超过键值的指定调用速率后建议的重试间隔(以秒为单位)。 不允许使用策略表达式。 Retry-After
retry-after-variable-name 策略表达式变量的名称,该变量用于存储在超过键值的指定调用速率后建议的重试间隔(以秒为单位)。 不允许使用策略表达式。 空值
remaining-calls-header-name 响应头的名称,每次执行策略后,其值为在 renewal-period 中指定的时间间隔内键值的允许剩余调用数。 不允许使用策略表达式。 空值
remaining-calls-variable-name 策略表达式变量的名称,该变量用于存储在每次执行策略后,renewal-period 中指定的时间间隔内键值的允许剩余调用数。 不允许使用策略表达式。 空值
total-calls-header-name 响应头的名称,其值为 calls 中指定的值。 不允许使用策略表达式。 空值

使用情况

使用注意事项

  • API 管理对策略中指定的每个 counter-key 值使用单个计数器。 在策略配置了此键值的所有作用域中,计数器都会更新。 如果要在不同的作用域(例如,特定 API 或产品)配置单独的计数器,请在不同的作用域指定不同的键值。 例如,将标识作用域的字符串追加到表达式的值。
  • 可以将自承载网关中的速率限制计数配置为在本地同步(在群集节点中的网关实例之间),例如,通过 Kubernetes 的 Helm 图表部署或使用 Azure 门户部署模板。 但是,速率限制计数不会与 API 管理实例中配置的其他网关资源同步,包括云中的托管网关。 了解详细信息

示例

在下面的示例中,可通过调用方 IP 地址对速率限制进行键控,将其控制为 每 60 秒 10 个调用。 每次执行策略后,在该时间段内允许用于此调用方 IP 地址的剩余调用存储在变量 remainingCallsPerIP 中。

<policies>
    <inbound>
        <base />
        <rate-limit-by-key calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

有关此策略的详细信息和示例,请参阅使用 Azure API 管理进行高级请求限制

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