按密钥限制调用速率
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 管理进行高级请求限制。
相关策略
后续步骤
有关使用策略的详细信息,请参阅:
- 教程:转换和保护 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 策略示例