此页面由 Cloud Translation API 翻译。

SpikeArrest 政策

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

Spike Arrest 政策通过 <Rate> 元素防止流量激增。此元素限制 API 代理处理并发送到后端的请求数，从而避免性能滞后和停机。

Spike Arrest 的工作原理

您可以将 Spike Arrest 视为一种用于避免流量高峰的方法，而不是将流量限制为特定请求数的方法。您的 API 和后端可以处理一定量的流量，而 Spike Arrest 政策帮助您将流量平滑地保持在您所需的常规量。

运行时 Spike Arrest 行为与您期望输入的每分钟或每秒字面量值产生的行为有所不同。

举例来说，假设您输入了一个 30pm 的速率（每分钟 30 个请求）。在测试时，您可能认为您可以在 1 秒内发送 30 个请求，只要在 1 分钟内即可。但该政策并非这样执行这种设置的。如果您思考一下就会明白，某些环境中 1 秒钟内 30 个请求会被视为是一个小型高峰。

那么，然后会怎么样呢？为防止出现类似高峰的行为，Spike Arrest 会将您的设置划分为若干更小的时间间隔，从而平滑发送允许的全部请求数：

每分钟速率可以以秒为时间间隔，平滑发送允许的全部请求。
例如，30pm 会按以下所示实现平滑发送：
60 秒（1 分钟）/30pm = 间隔时间为 2 秒，或每 2 秒允许 1 个请求。2 秒内发出的第二个请求将会失败。同时，一分钟内发出的第 31 个请求将会失败。
每秒速率会以毫秒为时间间隔，平滑发送允许的全部请求。
例如，10ps 会按以下所示实现平滑发送：
1000 毫秒（1 秒钟）/10ps = 间隔时间为 100 毫秒，或每 100 毫秒允许 1 个请求。100 毫秒内发出的第二个请求将会失败。同时，一秒钟内发出的第 11 个请求将会失败。

还有：1 个请求*消息处理器数量

默认情况下，除非您启用 <UseEffectiveCount>，否则 Spike Arrest 不会分布。这意味着请求数并非在消息处理器之间同步。由于使用的消息处理器不止一个，尤其是有些具有轮询配置，每个处理器都独立处理自己的 Spike Arrest 限制。一个消息处理器的情况下，30pm 的速率将流量平滑处理为每 2 秒 1 个请求 (60 / 30)。两个消息处理器（Edge Cloud 的默认设置）的情况下，该数字翻倍，为每 2 秒 2 个请求。因此，计算得出的每个时间间隔内的完整请求数乘以消息处理器数量就得出总体控制速率。

Spike Arrest 和配额之间的差异

配额政策配置允许客户端应用在一小时、一日、一周或一个月内提交给 API 的请求消息的数量。配额政策通过维护分布式计数器计算传入请求，从而对客户端应用强制执行使用限制。

使用配额可以强制执行与开发者和合作伙伴签署的业务合同或服务等级协议 (SLA)，而不是运营流量管理。使用 Spike Arrest 可防止 API 流量突然激增。另请参阅比较配额、Spike Arrest 和并发速率限制政策。

视频

以下视频介绍您如何使用 Spike Arrest 政策保护您的 API 远离流量高峰：

为什么需要它

如何配置

附加政策

每秒速率限制

每分钟速率限制

唯一速率限制

比较配额政策

流变量

`<SpikeArrest>` 元素

定义 Spike Arrest 政策。

默认值	请参阅下面的默认政策标签页
是否必需？	可选
类型	复杂对象
父元素	不适用
子元素	`<Identifier>` `<MessageWeight>` `<Rate>`（必需） `<UseEffectiveCount>`

语法

<SpikeArrest> 元素使用以下语法：

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

默认政策

以下示例显示您在 Edge 界面中向流添加 Spike Arrest 政策时的默认设置：

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
`name`	N/A	Required	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.
`continueOnError`	false	Optional	Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
`enabled`	true	Optional	Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
`async`	false	Deprecated	This attribute is deprecated.

示例

以下示例展示您可以使用 Spike Arrest 政策的一些方法：

示例 1

以下示例将速率设置为每秒 5 个：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

此政策将速率平滑处理为每 200 毫秒 (1000/5) 允许一个请求。

示例 2

以下示例将速率设置为每分钟 300 个：

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

有效速率为 300 次/分钟，这意味着系统会每 200 毫秒向存储分区添加一个新令牌。存储分区大小始终配置为 messagesPerPeriod 的 10%。因此，如果 messagesPerPeriod 为 300，则令牌桶大小为 30 个令牌。

示例 3

以下示例将请求限制为每分钟 12 个（每 5 秒 (60/12) 允许一个请求）：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

此外，<MessageWeight> 元素接受自定义值（weight 标头），用于针对特定应用或客户端调整消息权重。这为 <Identifier> 元素标识的实体提供了额外的控制限制。

示例 4

以下示例指示 Spike Arrest 查找通过作为 request.header.runtime_rate 流变量传递的请求所设置的运行时值：

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

流变量的值必须采用 intpm 或 intps 格式。

如需尝试此示例，请执行如下所示的请求：

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

子元素参考

本部分介绍 <SpikeArrest> 的子元素。

`<DisplayName>`

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	n/a
Required?	Optional. If you omit `<DisplayName>`, the value of the policy's `name` attribute is used
Type	String
Parent Element	<`PolicyElement`>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

`<Identifier>`

您可以选择对请求进行分组的方式，从而根据客户端应用 Spike Arrest 政策。例如，您可以按开发者 ID 对请求进行分组，这种情况下，每个开发者的请求将计入他们自己的 Spike Arrest 速率，而不是向代理进行的所有请求。

您可以将其与 <MessageWeight> 元素一起使用，从而更精细地控制请求限制。

如果您将 <Identifier> 元素留空，系统会对发送到该 API 代理的所有请求强制执行一个速率限制。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<SpikeArrest>`
子元素	无

语法

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>

示例 1

以下示例按开发者 ID 实施 Spike Arrest 政策：

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
</SpikeArrest>

下表介绍 <Identifier> 的属性：

属性	说明	默认值	状态
`ref`	确定 Spoke Arrest 组传入请求的变量。您可以使用任何流程变量来表示唯一客户端，例如使用 VerifyAPIKey 政策的客户端。此外，您还可以使用 JavaScript 政策或 AssignMessage 政策设置自定义变量。	不适用	必需

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

`<MessageWeight>`

指定为每条消息定义的权重。消息权重会修改单个请求对 Sprike Arrest 速率的影响。消息权重可以是任何流变量，例如 HTTP 标头、查询参数、表单参数或消息正文内容。您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。

您可以将其与 <Identifier> 结合使用，从而进一步按特定客户端或应用限制请求。

例如，如果 Spike Arrest <Rate> 为 10pm，而应用提交权重为 2 的请求，则该客户端每分钟只能发送 5 条消息，因为每个请求将计为 2。

默认值	不适用
是否必需？	可选
类型	整数
父元素	`<SpikeArrest>`
子元素	无

语法

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

示例 1

以下示例将请求限制为每分钟 12 个（每 5 秒 (60/12) 允许一个请求）：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

在此示例中，<MessageWeight> 接受自定义值（请求中的 weight 标头），用于针对特定客户端调整消息权重。这为 <Identifier> 元素标识的实体提供了额外的控制限制。

下表介绍 <MessageWeight> 的属性：

属性	说明	状态	默认
`ref`	标识包含特定客户端的消息权重的流变量。这可以是任何流程变量，例如 HTTP 查询参数、标头或消息正文内容。如需了解详情，请参阅流变量参考文档。此外，您还可以使用 JavaScript 政策或 AssignMessage 政策设置自定义变量。	必需	不适用

`<Rate>`

通过设置每分钟或每秒允许的请求数来指定采用哪个速率限制流量高峰（或爆发）。您还可以将该元素与 <Identifier> 和 <MessageWeight> 结合使用，通过接受客户端的值来在运行时平滑限制流量。

默认值	不适用
是否必需？	必需
类型	整数
父元素	`<SpikeArrest>`
子元素	无

语法

您可以通过以下某种方式指定速率：

指定为 <Rate> 元素的正文的静态速率
变量值，可由客户端传递；使用 ref 属性标识流变量的名称

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

有效的速率值（定义为变量值或在元素的正文中）必须遵循以下格式：

intps（每秒请求数，以毫秒为单位进行平滑处理）
intpm（每分钟的请求数，以秒为单位进行平滑处理）

int 的值必须是非零正整数。

示例 1

以下示例将速率设置为每秒 5 个请求：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

此政策将速率平滑处理为每 200 毫秒 (1000/5) 允许一个请求。

示例 2

以下示例将费率设置为每分钟 12 个请求：

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

此示例政策将速率平滑处理为每五秒 (60/12) 允许一个请求。

下表介绍 <Rate> 的属性：

属性说明状态默认

属性	说明	状态	默认
`ref`	标识用于指定速率的流变量。这可以是任何流程变量（例如 HTTP 查询参数、标头或消息正文内容），也可以是 KVM 等值。如需了解详情，请参阅流变量参考文档。您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。如果您同时定义 `ref` 和此元素的正文，则在请求中设置流变量时，系统会应用 `ref` 的值。（如果在请求中未设置 `ref` 中标识的变量，则正好相反）。例如： <Rate ref="request.header.custom_rate">1pm</Rate> 在此示例中，如果客户端没有传递“custom_rate”标头，则 API 代理的速率是所有客户端每分钟 1 个请求。如果客户端传递“custom_rate”标头，则速率限制是代理上所有客户端每秒 10 个请求，直到发送了没有“custom_rate”标头的请求。您可以使用 `<Identifier>` 对请求进行分组，以对不同类型的客户端强制执行自定义速率。如果您为 `ref` 指定了值，但没有在 `<Rate>` 元素的正文中设置速率，而客户端没有传递值，则 Sprike Arrest 政策会抛出一个错误。	可选	无

ref

标识用于指定速率的流变量。这可以是任何流程变量（例如 HTTP 查询参数、标头或消息正文内容），也可以是 KVM 等值。如需了解详情，请参阅流变量参考文档。

您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。

如果您同时定义 ref 和此元素的正文，则在请求中设置流变量时，系统会应用 ref 的值。（如果在请求中未设置 ref 中标识的变量，则正好相反）。

例如：

<Rate ref="request.header.custom_rate">1pm</Rate>

在此示例中，如果客户端没有传递“custom_rate”标头，则 API 代理的速率是所有客户端每分钟 1 个请求。如果客户端传递“custom_rate”标头，则速率限制是代理上所有客户端每秒 10 个请求，直到发送了没有“custom_rate”标头的请求。

您可以使用 <Identifier> 对请求进行分组，以对不同类型的客户端强制执行自定义速率。

如果您为 ref 指定了值，但没有在 <Rate> 元素的正文中设置速率，而客户端没有传递值，则 Sprike Arrest 政策会抛出一个错误。

可选

无

`<UseEffectiveCount>`

使用自动扩缩组时，将 Spike Arrest 计数分布到消息处理器 (MP) 之间。

注意：<UseEffectiveCount> 元素适用于 Edge Public Cloud，以及 Edge for Private Cloud 4.18.05 及更高版本。

语法

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

示例 1

以下示例将 <UseEffectiveCount> 设置为 true：

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

<UseEffectiveCount> 元素是可选字段；如果您从突发流量抑制政策中省略此元素，则默认值为 false。

注意：默认的 SpikeArrest 政策中包含 <UseEffectiveCount> 元素，并将其设置为 true。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<SpikeArrest>`
子元素	无

下表说明了 <UseEffectiveCount> 元素的属性：

属性	说明	默认值	状态
`ref`	标识包含 `<UseEffectiveCount>` 值的变量。这可以是任何流变量，例如 HTTP 查询参数、标头或消息正文内容。如需了解详情，请参阅流变量参考文档。此外，您还可以使用 JavaScript 政策或 AssignMessage 政策设置自定义变量。	不适用	可选

<UseEffectiveCount> 的效果取决于其值：

true：MP 的尖峰速率限制为 <Rate> 除以同一 Pod 中的当前 MP 数量。汇总限制是 <Rate> 的值。动态添加（或移除）MP 后，其各自的激增率上限将会增加（或减少），但总上限将保持不变。
false（如果省略，则默认值为 false）：每个 MP 的尖峰速率限制只是其 <Rate> 的值。总上限是所有 MP 费率的总和。添加（或移除）MP 后，其各自的激增率上限将保持不变，但总上限将增加（或减少）。

下表显示了 <UseEffectiveCount> 对每个 MP 的有效速率限制的影响：

	`<UseEffectiveCount>` 的值
	`false`	`false`	`false`	`true`	`true`	`true`
MP 数量	8	4	2	8	4	2
`<Rate>` 的值	10	10	10	40	40	40
每 MP 的有效费率	10	10	10	5	10	20
汇总限制	80	40	20	40*	40*	40*
* 与 `<Rate>` 相同。

在此示例中，请注意，当 MP 数量从 4 减少到 2，且 <UseEffectiveCount> 为 false 时，每个 MP 的有效费率保持不变（为 10）。但是，当 <UseEffectiveCount> 为 true 时，如果 MP 数量从 4 个减少到 2 个，则每个 MP 的有效费率会从 10 提高到 20。

提示：将 <UseEffectiveCount> 设置为 true 时，请将 <Rate> 设置为目标汇总上限。

流变量

当执行 Sprike Arrest 政策时，系统会填充以下流变量：

变量	类型	权限	说明
`ratelimit.policy_name.failed`	布尔值	只读	指示政策是否失败（`true` 或 `false`）。

如需了解详情，请参阅流变量参考文档。

错误参考信息

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.

Fault code	HTTP status	Cause
`policies.ratelimit.FailedToResolveSpikeArrestRate`	`500`	This error occurs if the reference to the variable containing the rate setting within the `<Rate>` element cannot be resolved to a value within the Spike Arrest policy. This element is mandatory and used to specify the spike arrest rate in the form of `intpm` or `intps`.
`policies.ratelimit.InvalidMessageWeight`	`500`	This error occurs if the value specified for the `<MessageWeight>` element through a flow variable is invalid (a non-integer value).
`policies.ratelimit.SpikeArrestViolation`	`429`	The rate limit was exceeded. Note: For Private Cloud, the default HTTP status code returned is `500`. To change the status code returned to `429`, set this property with the API call described in Example fault rule

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidAllowedRate`	If the spike arrest rate specified in the `<Rate>` element of the Spike Arrest Policy is not an integer or if the rate does not have `ps` or `pm` as a suffix, then the deployment of the API proxy fails.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "SpikeArrestViolation"`
`ratelimit.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`ratelimit.SA-SpikeArrestPolicy.failed = true`

Example error response

Shown below is an example error response:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

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

超出配额或 Spike Arrest 政策设置的速率限制的当前 HTTP 状态代码为 429（请求过多）。如需将 HTTP 状态代码更改为 500（内部服务器错误），请使用更新组织属性 API 将 features.isHTTPStatusTooManyRequestEnabled 属性设置为 false。

Private Cloud：对于 Private Cloud，返回的默认 HTTP 状态代码为 500。如需将返回的状态代码更改为 429，请使用以下 API 调用设置此属性：

注意：更新属性时，即使未更改所有现有属性，也必须将其传递给 API。如果您在载荷中省略属性，则系统会移除这些属性。

curl -u email:password -X POST -H "Content-type:application/xml" \
  http://edge-management-server:8080/v1/o/myorg \
  -d '<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Environments/>
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
    </Properties>
  </Organization>'

例如：

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

SpikeArrest 政策

Spike Arrest 的工作原理

还有：1 个请求*消息处理器数量

Spike Arrest 和配额之间的差异

视频

为什么需要它

如何配置

附加政策

每秒速率限制

每分钟速率限制

唯一速率限制

比较配额政策

流变量

<SpikeArrest> 元素

语法

默认政策

示例

示例 1

示例 2

示例 3

示例 4

子元素参考

<DisplayName>

Syntax

Example

<Identifier>

语法

示例 1

<MessageWeight>

语法

示例 1

<Rate>

语法

示例 1

示例 2

<UseEffectiveCount>

语法

示例 1

流变量

错误参考信息

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

架构

相关主题

`<SpikeArrest>` 元素

`<DisplayName>`

`<Identifier>`

`<MessageWeight>`

`<Rate>`

`<UseEffectiveCount>`