通过

你当前正在访问 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 管理进行高级请求限制。

相关内容

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