按订阅限制调用速率

2025-06-09

适用于：所有 API 管理层级

rate-limit 策略可以对调用速率进行限制，使每个指定时段的调用不超出指定的数目，避免单个订阅的 API 使用量暴增。超过调用速率时，调用方会收到 429 Too Many Requests 响应状态代码。

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

注意

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

注意

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

策略语句

<rate-limit calls="number" renewal-period="seconds"  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">
    <api name="API name" id="API id" calls="number" renewal-period="seconds" >
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" />
    </api>
</rate-limit>

属性

属性	说明	需要	默认
调用	在 `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（应用程序编程接口）	添加一个或多个此类元素，对产品中的 API 施加调用速率限制。产品和 API 的调用速率限制是分别应用的。可以通过 `name` 或 `id` 引用 API。如果同时提供了这两个属性，则将使用 `id` 并忽略 `name`。	否
操作	添加一个或多个此类元素，对 API 中的操作施加调用速率限制。产品、API 和操作的调用速率限制是分别应用的。可以通过 `name` 或 `id` 引用 Operation。如果同时提供了这两个属性，则将使用 `id` 并忽略 `name`。	否

api 属性

属性	说明	需要	默认
姓名	要对其应用速率限制的 API 的名称。	必须指定 `name` 或 `id`。	不适用
id	要对其应用速率限制的 API 的 ID。	必须指定 `name` 或 `id`。	不适用
调用	在 `renewal-period` 所指定的时间间隔内允许的最大总调用数。不允许使用策略表达式。	是	不适用
续订期	滑动窗口的长度（以秒为单位），在此期间，允许的请求数不应超过 `calls` 中指定的值。允许的最大值：300 秒。不允许使用策略表达式。	是	不适用

操作属性

属性	说明	需要	默认
姓名	要对其应用速率限制的操作的名称。	必须指定 `name` 或 `id`。	不适用
id	要对其应用速率限制的操作的 ID。	必须指定 `name` 或 `id`。	不适用
调用	在 `renewal-period` 所指定的时间间隔内允许的最大总调用数。不允许使用策略表达式。	是	不适用
续订期	滑动窗口的长度（以秒为单位），在此期间，允许的请求数不应超过 `calls` 中指定的值。允许的最大值：300 秒。不允许使用策略表达式。	是	不适用

使用情况

策略节：入站
策略范围：产品、API、操作
网关：经典、消耗、自承载

使用注意事项

每个策略定义只能使用此策略一次。
此策略仅在使用订阅密钥来访问 API 时应用。
可以将自承载网关中的速率限制计数配置为在本地同步（在群集节点中的网关实例之间），例如，通过 Kubernetes 的 Helm 图表部署或使用 Azure 门户部署模板。但是，速率限制计数不会与 API 管理实例中配置的其他网关资源同步，包括云中的托管网关。了解详细信息

示例

在下面的示例中，每个订阅的速率限制为每 90 秒 20 个调用。每次执行策略后，在该时间段内允许的剩余调用存储在变量 remainingCallsPerSubscription 中。

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

速率限制和配额

后续步骤

有关使用策略的详细信息，请参阅：

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例

通过