配额政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

内容

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

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

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

视频

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

示例

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

<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>

<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>

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

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

<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>

<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>

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

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

<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>

配额政策简介

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

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

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

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

配额政策类型

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

对于 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:00 和 24: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">

以下属性特定于此政策。

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<Allow> 元素

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

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

<Allow count="2000"/> 

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

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

如果您同时指定 count 和 countRef，则 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_time 或 off_peak_time。如果查询参数包含无效值，则该政策将返回配额违规错误。

属性

<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_time 和 off_peak_time 的两个配额计数器。

属性

<Interval> 元素

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

例如，含 hour 的 TimeUnit 的 24 的Interval 表示配额将在 24 小时内计算。

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

属性

<TimeUnit> 元素

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

例如，含 hour 的 TimeUnit 的 24 的Interval 表示配额将在 24 小时内计算。

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

属性

<StartTime> 元素

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

例如：

<StartTime>2017-7-16 12:00:00</StartTime>

<Distributed> 元素

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

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

<Distributed>true</Distributed>

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

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous> 元素

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

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

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

<Synchronous>false</Synchronous>

<AsynchronousConfiguration> 元素

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

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

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

或

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

<AsynchronousConfiguration>/<SyncIntervalInSeconds> 元素

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

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

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

<AsynchronousConfiguration>/<SyncMessageCount> 元素

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

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

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

<Identifier> 元素

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

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

以下 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"/>

属性

<MessageWeight> 元素

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

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

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

<MessageWeight ref="message_weight"/>

流变量

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

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 和并发速率限制政策