配额政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

使用配额政策配置 API 代理在一段时间(例如分钟、小时、日、周或月)内允许的请求消息数量。您可以将所有访问 API 代理的应用都设置为相同配额,也可以根据以下项设置配额:

  • 包含 API 代理的产品
  • 请求 API 的应用
  • 应用开发者
  • 许多其他条件

请勿使用配额来防范总体流量高峰。为此,请使用 Sparke Arrest 政策请参阅 Spike Arrest 政策

视频

以下视频介绍如何使用配额政策管理配额:

简介(新版 Edge)

简介(经典 Edge)

动态配额

分布式与同步

消息权重

日历

滚动窗口

Flexi

条件配额

流变量

错误处理

示例

以下政策代码示例说明了如何通过以下项开始和结束配额周期:

更动态的配额

<Quota name="CheckQuota"> 
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

借助动态配额,您可以配置单个配额政策,以便根据传递给配额政策的信息强制执行不同的配额设置。此上下文中配额设置的另一个术语是“服务计划”。动态配额会检查应用的“服务计划”,然后强制执行这些设置。

注意:如果同时为元素指定值和引用,则引用将优先。如果引用在运行时未解析,则使用值。

例如,在创建 API 产品时,您可以选择设置允许的配额限制、时间单位和时间间隔。但是,在 API 产品上设置这些值不会强制在 API 代理中使用它们。此外,您还必须向读取这些值的 API 代理添加配额政策。如需了解详情,请参阅创建 API 产品

在上面的示例中,包含配额政策的 API 代理使用名为 verify-api-key 的 VerifyAPIKey 政策来验证请求中传递的 API 密钥。接着,配额政策会从 VerifyAPIKey 政策访问流变量,以读取 API 产品上设置的配额值。如需详细了解 VerifyAPIKey 流变量,请参阅验证 API 密钥政策

另一个选项是为各个开发者或应用设置自定义属性,然后在配额政策中读取这些值。例如,您希望为每个开发者设置不同的配额值。在这种情况下,您可以在开发者上设置包含限制、时间单位和间隔的自定义属性。然后,您可以在配额政策中引用这些值,如下所示:

<Quota name="DeveloperQuota"> 
  <Identifier ref="verifyapikey.verify-api-key.client_id"/> 
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> 
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> 
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> 
</Quota>

此示例还使用 VerifyAPIKey 流变量来引用在开发者上设置的自定义属性。

您可以使用任意变量来设置配额政策的参数。这些变量可以来自:

  • 流变量
  • 关于 API 产品、应用或开发者的属性
  • 键值对映射 (KVM)
  • 标头、查询参数、表单参数等

对于每个 API 代理,您可以添加一个配额政策来引用与所有其他代理的所有其他配额政策相同的变量,或者配额政策可以引用该政策和代理的唯一变量。

开始时间

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

对于 type 设置为 calendar 的配额,您必须定义一个显式 <StartTime> 值。时间值为 GMT 时间,而不是本地时间。如果您未为 calendar 类型的政策提供 <StartTime> 值,则 Edge 会发出错误。

每个应用的配额计数器都将根据 <StartTime><Interval><TimeUnit> 值刷新。在本示例中,配额从 GMT 2017 年 2 月 18 日上午 10:30 开始计算,每 5 小时刷新一次。因此,下次刷新时间为 GMT 2017 年 2 月 18 日下午 3:30。

访问计数器

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

API 代理可以访问由配额政策设置的流变量。您可以在 API 代理中访问这些流变量以执行条件处理,在接近配额限制时监控政策,将当前配额计数器返回给应用,或出于其他原因。

由于对政策的流变量的访问基于政策 name 属性,因此对于上述名为 QuotaPolicy 的政策,您可以通过以下格式访问其流变量:

  • ratelimit.QuotaPolicy.allowed.count:允许的计数。
  • ratelimit.QuotaPolicy.used.count:当前计数器值。
  • ratelimit.QuotaPolicy.expiry.time:计数器重置的 UTC 时间。

您还可以访问许多其他流变量,如下所述。

例如,您可以使用以下 AssignMessage 政策,将配额流变量的值作为响应标头返回:

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

第一个请求

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

使用此示例代码,强制执行每小时 10,000 次调用的配额。该政策会在每个小时的顶部重置配额计数器。如果计数器在一小时结束之前达到 10,000 次调用配额,则超出 10,000 次的调用将被拒绝。

例如,如果计数器在 2017-07-08 07:00:00 开始,则会在 2017-07-08 08:00:00(从开始时间算起 1 小时)重置为 0。如果在 2017-07-08 07:35:28 收到第一个消息,且消息计数在 2017-07-08 08:00:00 之前达到 10,000,则超出该计数的调用将被拒绝,直到计数在小时的顶部重置为止。

计数器重置时间基于 <Interval><TimeUnit> 的组合。例如,如果将 <Interval> 设置为 12(对于小时的 <TimeUnit>),则计数器会每 12 小时重置一次。您可以将 <TimeUnit> 设置为分钟、小时、天、周或月。

您可以在 API 代理中的多个位置引用此政策。例如,您可以将其放在代理 PreFlow 上,使其针对每个请求执行。或者,您可以将其放在 API 代理的多个流中。如果您在代理的多个位置使用此政策,则该政策会维护一个由该政策的所有实例更新的单个计数器。

或者,您可以在 API 代理中定义多个配额政策。每个配额政策都根据政策的 name 属性维护自己的计数器。

设置标识符

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

默认情况下,无论请求的来源如何,配额政策都会为 API 代理定义一个计数器。或者,您也可以将 <Identifier> 属性与配额政策搭配使用,根据 <Identifier> 属性的值来维护单独的计数器。

例如,使用 <Identifier> 标记为每个客户端 ID 定义单独的计数器。然后,客户端应用会向您的代理请求传递一个包含 clientID 的标头,如上例所示。

您可以为 <Identifier> 属性指定任何流变量。例如,您可以指定名为 id 的查询参数包含唯一标识符:

<Identifier ref="request.queryparam.id"/>

如果您使用 VerifyAPIKey 政策来验证 API 密钥,或将 OAuthV2 政策与 OAuth 令牌搭配使用,则可以使用 API 密钥或令牌中的信息为同一配额政策定义单个计数器。例如,以下 <Identifier> 标记使用名为 verify-api-key 的 VerifyAPIKey 政策的 client_id 流变量:

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

现在,每个唯一 client_id 值都会在配额政策中定义自己的计数器。

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

您可以使用基于类的配额计数来动态设置配额限制。在此示例中,配额限制由随每个请求传递的 developer_segment 标头的值决定。该变量的值可以是 platinumsilver。如果标头具有无效值,则该政策会返回配额违规错误。


配额政策简介

配额是 API 代理可以在某个时间段(例如分钟、小时、天、周或月)内处理的请求消息配额。该政策将维护计数器,记录 API 代理收到的请求数量。借助此功能,API 提供商可以在某个时间段内应用执行的 API 调用数量强制执行限制。例如,您可以通过配额政策,将应用限制为每分钟 1 个请求,或者每月 10,000 个请求。

例如,如果将配额定义为每月 10,000 条消息,则速率限制会在第 10,000 条消息之后开始。是在该期间的第一天还是最后一天计算达到 10,000 条消息,都无关紧要;在指定时间间隔结束时配额计数器自动重置之前,或者使用重置配额政策显式重置置配额之前,不允许其他请求区域。

名为 SpikeArrest 的配额变异可防止因使用量的突然增加、错误客户端或恶意攻击而出现流量高峰(或爆发)。如需详细了解 SpikeArrest 政策,请参阅 Spike Arrest 政策

配额适用于各个 API 代理,并且不分布在 API 代理中。例如,如果您在某个 API 产品中有三个 API 代理,则这三个代理不会共享单个配额,即使这三个代理使用相同的配额政策配置也是如此。

配额政策类型

配额政策支持以下几种不同类型的政策:默认、calendarflexirollingwindow。每种类型都指定了配额计数器的开始时间和重置时间,如下表所示:

时间单位 默认(或 null)重置 日历重置 Flexi 重置
分钟 下一分钟开始 <StartTime> 晚一分钟 发出第一个请求后的 1 分钟
hour 下一小时的顶部 <StartTime> 后一小时 发出第一个请求后的一小时
当天午夜 (GMT) <StartTime> 晚 24 小时 发出第一次请求后的 24 小时
当周结束时的 GMT 周日午夜 <StartTime> 晚一周 发出第一次请求后的一周
当月最后一天的午夜 (GMT) <StartTime> 之后的一个月(28 天) 第一个请求之后的一个月(28 天)

对于 type="calendar",您必须指定 <StartTime> 的值。

该表未列出 rollingwindow 类型的值。滚动窗口配额的工作原理是设置配额“窗口”的大小,例如一小时或一天的窗口。收到新请求时,政策会确定配额在过去的时间“窗口”内是否超出配额。

例如,您定义了允许 1000 个请求的两小时窗口。下午 4:45 收到新请求。该政策计算过去两小时窗口的配额计数,即自下午 2:45 以来的请求数量。如果在两小时窗口内未超过配额限制,则系统会允许该请求。

1 分钟后,即在下午 4:46 收到另一个请求。现在,该政策从下午 2:46 开始计算配额,以确定是否超出限制。

对于 rollingwindow 类型,计数器从不重置,但是会在每个请求重新计算。

了解配额计数器

默认情况下,无论 API 代理中引用多少次,配额政策都维护单个计数器。配额计数器的名称基于政策的 name 属性。

例如,您创建一个名为 MyQuotaPolicy 的配额政策,限制 5 个请求,并将其放在 API 代理中的多个流(流 A、B 和 C)中。即使它用于多个流中,也会维护一个由该政策的所有实例更新的单个计数器:

  • 执行流 A -> 执行 MyQuotaPolicy,且其计数器 = 1
  • 执行流程 B -> 执行 MyQuotaPolicy,且其计数器 = 2
  • 执行流 A -> 执行 MyQuotaPolicy,且其计数器 = 3
  • 执行流程 C -> 执行 MyQuotaPolicy,且其计数器 = 4
  • 执行流 A -> 执行 MyQuotaPolicy,且其计数器 = 5

对其中任何三个流的下一个请求都会被拒绝,因为配额计数器已达到其限制。

在 API 代理流程中的多个位置使用同一配额政策可能会导致配额用尽速度超出预期,这是一种反模式,请参阅 Apigee Edge 反模式手册

或者,您也可以在 API 代理中定义多个配额政策,并在每个流中使用不同的政策。每个配额政策都根据政策的 name 属性维护自己的计数器。

或者,使用配额政策中的 <Class><Identifier> 元素在单个政策中定义多个唯一计数器。通过使用这些元素,单个政策可以根据发出请求的应用、发出请求的应用开发者、客户端 ID 或其他客户端标识符等,维护不同的计数器。如需详细了解如何使用 <Class><Identifier> 元素,请参阅上面的示例。

时间表示法

所有配额时间均设置为世界协调时间 (UTC) 时区。

配额时间表示法遵循国际标准 ISO 8601 中定义的国际标准日期表示法。

日期采用以下格式定义为年、月和天:YYYY-MM-DD。例如,2015-02-04 表示 2015 年 2 月 4 日。

时间采用以下格式定义为小时、分钟和秒:hours:minutes:seconds。例如,23:59:59 表示午夜前 1 秒的时间。

请注意,您可以使用 00:00:0024:00:00 两种表示法来区分可与一个日期相关联的两个午夜。因此,2015-02-04 24:00:00 是与 2015-02-05 00:00:00 相同的日期和时间。后者通常是首选表示法。

从 API 产品配置获取配额设置

您可以在 API 产品配置中设置配额限制。这些限制不会自动强制执行配额。您可以在配额政策中引用产品配额设置。在产品上设置配额以供配额政策应用具有以下优势:

  • 配额政策可以对 API 产品中的所有 API 代理使用统一设置。
  • 您可以对 API 产品的配额设置进行运行时更改,并且引用该值的配额政策会自动更新配额值。

如需详细了解如何使用 API 产品中的配额设置,请参阅上面的“动态配额”示例。.

如需了解如何使用配额限制配置 API 产品,请参阅创建 API 产品

元素参考

下面是您可以在此政策中配置的元素和属性。请注意,某些元素组合相互排斥或不需要。查看特定用法的示例。使用名为“VerifyAPIKey”的 Verify API Key 政策检查请求中的应用 API 密钥时,默认情况下可以使用以下 verifyapikey.VerifyAPIKey.apiproduct.* 变量。变量值来自与密钥关联的 API 产品的配额设置,如从 API 产品配置获取配额设置中所述。

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

<Quota> 属性

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

以下属性特定于此政策。

属性 说明 默认 状态
类型

用于确定配额计数器检查配额使用情况的时间和方式。如需了解详情,请参阅配额政策类型

如果省略 type 值,则计数器将从分钟/小时/天/周/月的开始处开始。

有效值包括:

  • calendar:根据显式开始时间配置配额。系统会根据您设置的 <StartTime><Interval><TimeUnit> 值刷新每个应用的配额计数器。
  • rollingwindow:配置使用“滚动窗口”确定配额用量的配额。借助 rollingwindow,您可以使用 <Interval><TimeUnit> 元素确定窗口的大小;例如,1 天。收到请求时,Edge 会查看请求的确切时间(例如:下午 5:01),并计算前一天(1 天)那个时间和下午 5:01 之间收到的请求数量。并确定在该窗口内是否超出配额。
  • flexi:配置配额,使计数器在从应用收到第一个请求消息时开始,并根据 <Interval>, <TimeUnit> 值重置。
日历 选填

下表介绍了所有政策父元素通用的特性:

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

true 可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 name 属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素,则会使用政策的 name 属性的值。

状态 可选
类型 字符串

<Allow> 元素

指定配额的计数限制。如果政策的计数器达到此限制值,则后续调用将被拒绝,直到计数器重置。

下面显示了设置 <Allow> 元素的三种方法:

<Allow count="2000"/> 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

如果您同时指定 countcountRef,则 countRef 优先。如果 countRef 在运行时未解析,则使用 count 的值。

默认: 不适用
状态: 选填
类型: 整数

属性

特性 说明 默认 状态
计数

用于指定配额的消息计数。

例如,count 属性值为 100、Interval 为 1,以及月份的 TimeUnit 指定配额为每个月 100 条消息。

2000 选填
countRef

用于指定包含配额的消息计数的流变量。countRef 优先于 count 属性。

选填

<Allow>/<Class> 元素

<Class> 元素让您可根据流变量的值对 <Allow> 元素设置条件。对于 <Class> 的每个不同 <Allow> 子标记,该政策会维护不同的计数器。

如需使用 <Class> 元素,请使用 <Class> 标记的 ref 属性指定流变量。Edge 随后使用流变量的值选择其中一个 <Allow> 子标记,以确定政策允许的计数。Edge 将流变量的值与 <Allow> 标记的 class 属性进行匹配,如下所示:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

在此示例中,当前配额计数器由随每个请求传递的 time_variable 查询参数的值决定。该变量的值可以是 peak_timeoff_peak_time。如果查询参数包含无效值,则该政策将返回配额违规错误。

默认: 不适用
状态: 选填
类型: 不适用

属性

特性 说明 默认 状态
ref

用于指定包含配额的配额类的流变量。

必需

<Allow>/<Class>/<Allow> 元素

<Allow> 元素指定 <Class> 元素定义的配额计数器的限制。对于每个 <Class> 不同的 <Allow> 子标记,该政策会维护不同的计数器。

例如:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

在此示例中,配额政策维护名为 peak_timeoff_peak_time 的两个配额计数器。

默认: 不适用
状态: 选填
类型: 不适用

属性

特性 说明 默认 状态

定义配额计数器的名称。

必需
计数 指定计数器的配额限制。 必需

<Interval> 元素

用于指定将与您指定的 TimeUnit(分钟、小时、天、周或月)配对的整数(例如 1、2、5、60 等),以确定 Edge 计算配额用量的时间段。

例如,含 hourTimeUnit24Interval 表示配额将在 24 小时内计算。

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
默认:
状态: 必需
类型: 整数

属性

特性 说明 默认 状态
ref

用于指定包含配额间隔的流变量。ref 优先于显式间隔值。如果同时指定了引用和值,则引用优先。如果 ref 在运行时未解析,则使用值。

选填

<TimeUnit> 元素

用于指定适用于配额的时间单位。

例如,含 hourTimeUnit24Interval 表示配额将在 24 小时内计算。

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
默认:
状态: 必需
类型:

字符串。从 minutehourdayweekmonth 中选择。

属性

特性 说明 默认 状态
ref 用于指定包含配额的时间单位的流变量。ref 优先于显式间隔值。如果 ref 在运行时未解析,则使用值。 选填

<StartTime> 元素

type 设置为 calendar, 时,会指定配额计数器开始计数的日期和时间,而不管是否从任何应用收到任何请求。

显式将 type 设置为 calendar, 时,必须提供显式 StartTime。您不能使用流变量的引用。如果在未设置 type 时指定 StartTime 值,则将收到错误。

例如:

<StartTime>2017-7-16 12:00:00</StartTime>
默认:
状态: type 设置为 calendar 时需要。
类型:

采用 ISO 8601 日期和时间格式的字符串。

<Distributed> 元素

安装 Edge 可以使用一个或多个消息处理器来处理请求。将此元素设置为 true 以指定政策应保留一个中心计数器,并在所有消息处理器中持续对其进行同步。消息处理器可以跨可用区域和/或地区。

如果使用 false 的默认值,则您可能会超出配额,因为不共享每个消息处理器的计数:

<Distributed>true</Distributed>

如需保证计数器已同步,并且对每个请求进行更新,请将 <Distributed><Synchronous> 设置为 true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
默认: false
状态: 选填
类型: 布尔值

<Synchronous> 元素

设置为 true 可同步更新分布式配额计数器。这意味着对计数器的更新与对 API 的请求检查配额将同时进行。如果不允许您通过该配额进行任何 API 调用,则设置为 true

设置为 false 可异步更新配额计数器。这意味着,某些超出配额的 API 调用可能会进行,具体取决于何时异步更新中央存储区中的配额计数器。但是,您不会面临与同步更新关联的潜在性能影响。

默认的异步更新间隔为 10 秒。使用 AsynchronousConfiguration 元素配置此异步行为。

<Synchronous>false</Synchronous>
默认: false
状态: 选填
类型: 布尔值

<AsynchronousConfiguration> 元素

当政策配置元素 <Synchronous> 不存在或存在并设置为 false 时,在分布式配额计数器之间配置同步间隔。

您可以使用 SyncIntervalInSecondsSyncMessageCount 子元素在某个时间段或消息计数后同步。它们是互斥的。例如:

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
默认: SyncIntervalInSeconds = 10 秒
状态: 可选;在 <Synchronous> 设置为 true 时忽略。
类型:

建筑

<AsynchronousConfiguration>/<SyncIntervalInSeconds> 元素

使用此项可替换在 10 秒间隔之后执行异步更新的默认行为。

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

按照限制主题中的说明,同步间隔必须 >= 10 秒。

默认: 10
状态: 选填
类型:

整数

<ASYNCConfiguration>/<SyncMessageCount> 元素

指定配额更新之间所有 Apigee 消息处理器的请求数。

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

此示例指定配额在每个 Apigee Edge 消息处理器中每 5 个请求更新配额计数一次。

默认: 不适用
状态: 选填
类型:

整数

<Identifier> 元素

使用 <Identifier> 元素配置政策,以便根据流变量创建唯一计数器。

您可以为流变量定义的特征创建唯一计数器。例如,您可以使用开发者电子邮件地址将配额与特定开发者关联。无论是使用自定义变量还是预定义变量(例如 Verify API Key 政策可用的变量),您都可以使用各种变量来标识配额。另请参阅变量参考文档

如果您不使用此元素,则政策会使用针对配额应用的单个计数器。

以下 Apigee 社区帖子中也有讨论此元素: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html

<Identifier ref="verifyapikey.verify-api-key.client_id"/>
默认: 不适用
状态: 选填
类型:

字符串

属性

特性 说明 默认 状态
ref

指定一个流变量来标识要用于请求的计数器。标识符可以是每个应用、应用用户、应用开发者、API 产品或其他特征唯一的 HTTP 标头、查询参数、表单参数或消息内容。

最常用于唯一标识应用的 <Identifier>client_idclient_id 是 API 密钥(或使用方密钥)的名称,是在 Apigee Edge 中的组织注册应用时为其生成的名称。如果您已为 API 启用 API 密钥或 OAuth 授权政策,则可以使用此标识符。

在某些情况下,必须在无 client_id 可用时检索配额设置,例如,未制定安全政策时。在这些情况下,您可以使用 Access Entity 政策检索相应的 API 产品设置,然后使用 ExtractVariables 提取值,然后在配额政策中使用提取的上下文变量。如需了解详情,请参阅 Access Entity 政策

不适用 选填

<MessageWeight> 元素

用于指定分配给每条消息的权重。使用消息权重提高请求消息的影响,例如,比其他消息消耗更多计算资源的请求消息。

例如,您希望将 POST 消息计为 GET 消息的两倍“重量”或费用。因此,对于 POST 将 MessageWeight 设置为 2,而对于 GET 设置为 1。您甚至可以将 MessageWeight 设置为 0,以使请求不会影响计数器。在本示例中,如果配额为每分钟 10 条消息,并且 POST 请求的 MessageWeight2,则配额在任何 10 分钟间隔内允许 5 个 POST 请求。在计数器重置之前,任何额外的请求(POST 或 GET)都将被拒绝。

表示 MessageWeight 的值必须由流变量指定,并且可从 HTTP 标头、查询参数、XML 或 JSON 请求载荷或任何其他流变量中提取。例如,您可以在名为 weight 的标头中对其进行设置:

<MessageWeight ref="message_weight"/>
默认: 不适用
状态: 选填
类型:

整数

流变量

当执行配额政策时,会自动填充以下预定义的流变量。如需详细了解流变量,请参阅变量参考

变量 类型 权限 说明
ratelimit.{policy_name}.allowed.count 只读 返回允许的配额计数
ratelimit.{policy_name}.used.count 只读 返回配额间隔内使用的当前配额
ratelimit.{policy_name}.available.count 只读 返回配额间隔内的可用配额计数
ratelimit.{policy_name}.exceed.count 只读 在超出配额后返回 1。
ratelimit.{policy_name}.total.exceed.count 只读 在超出配额后返回 1。
ratelimit.{policy_name}.expiry.time 只读

返回以毫秒为单位的 UTC 时间,该时间决定了配额何时失效,以及新的配额间隔何时开始。

如果配额政策类型为 rollingwindow,则此值无效,因为配额间隔永不失效。

ratelimit.{policy_name}.identifier 字符串 只读 返回附加到政策的(客户端)标识符引用
ratelimit.{policy_name}.class 字符串 只读 返回与客户端标识符关联的类
ratelimit.{policy_name}.class.allowed.count 只读 返回类中定义的允许配额计数
ratelimit.{policy_name}.class.used.count 只读 返回类中使用的配额
ratelimit.{policy_name}.class.available.count 只读 返回类中的可用配额计数
ratelimit.{policy_name}.class.exceed.count 只读 返回超出当前配额间隔中类限制的请求计数
ratelimit.{policy_name}.class.total.exceed.count 只读 返回超出所有配额间隔内类限制的请求总计数,因此它是所有配额间隔的 class.exceed.count 总和。
ratelimit.{policy_name}.failed 布尔值 只读

指明政策是否失败(true 或 false)。

错误参考信息

本部分介绍了在此政策触发错误时返回的错误代码和错误消息,以及 Edge 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息处理故障

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 如果未在配额政策中定义 <Interval> 元素,就会出现此错误。此元素是必需的,用于指定配额所适用的时间间隔。时间间隔可以是使用 <TimeUnit> 元素定义的分钟、小时、天、周或月。
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 如果未在配额政策中定义 <TimeUnit> 元素,就会出现此错误。此元素是必需的,用于指定配额所适用的时间单位。时间间隔可以是分钟、小时、天、周或月。
policies.ratelimit.InvalidMessageWeight 500 如果通过流变量指定的 <MessageWeight> 元素的值无效(非整数值),就会出现此错误。
policies.ratelimit.QuotaViolation 500 超过配额限制。 不适用

部署错误

错误名称 原因 修复
InvalidQuotaInterval 如果 <Interval> 元素中指定的配额间隔不是整数,则 API 代理的部署将失败。例如,如果在 <Interval> 元素中指定的配额间隔为 0.1,则 API 代理的部署将失败。
InvalidQuotaTimeUnit 如果 <TimeUnit> 元素中指定的时间单位不受支持,则 API 代理的部署将失败。支持的时间单位包括 minutehourdayweekmonth
InvalidQuotaType 如果 <Quota> 元素中的 type 属性指定的配额类型无效,则 API 代理的部署将失败。支持的配额类型包括 defaultcalendarflexirollingwindow
InvalidStartTime 如果 <StartTime> 元素中指定的时间格式无效,则 API 代理的部署将失败。有效格式为 yyyy-MM-dd HH:mm:ss,这是 ISO 8601 日期和时间格式。例如,如果在 <StartTime> 元素中指定的时间为 7-16-2017 12:00:00,则 API 代理的部署将失败。
StartTimeNotSupported 如果指定的 <StartTime> 元素的配额类型不是 calendar 类型,则 API 代理的部署将失败。仅 calendar 配额类型支持 <StartTime> 元素。例如,如果在 <Quota> 元素中将 type 属性设置为 flexirolling window,则 API 代理的部署将失败。
InvalidTimeUnitForDistributedQuota 如果将 <Distributed> 元素设置为 true 且将 <TimeUnit> 元素设置为 second,则 API 代理的部署将失败。时间单位 second 对于分配的配额无效。
InvalidSynchronizeIntervalForAsyncConfiguration 如果在配额政策的 <AsynchronousConfiguration> 元素中为 <SyncIntervalInSeconds> 元素指定的值小于 0,则 API 代理的部署将失败。
InvalidAsynchronizeConfigurationForSynchronousQuota 如果在配额政策中将 <AsynchronousConfiguration> 元素的值设置为 true,并且还使用 <AsynchronousConfiguration> 元素定义异步配置,则 API 代理的部署将失败。

故障变量

此政策触发错误时设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息

变量 其中 示例
fault.name="fault_name" fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 ratelimit.QT-QuotaPolicy.failed = true

错误响应示例

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

故障规则示例

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

架构

相关主题

ResetQuota 政策

SpikeArrest 政策

比较配额、Spike Arrest 和并发速率限制政策