SpikeArrest 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

Edge 界面中的 Spike Arrest 图标

Spike Arrest 政策通过 <Rate> 元素防止流量激增。此元素限制 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>

默认政策

以下示例显示了将“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>

此元素具有所有政策中常见的以下属性：

属性 默认 是否必需？ 说明
name N/A 必需

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

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError false 可选 设置为“false” 可在政策失败时返回错误。这是大多数政策的预期行为。如果设置为“true”，则即使政策失败，仍可继续执行流。
enabled 是 可选 设为“true”可强制执行政策。设为“false”可“关闭”政策。即使政策仍附加到某个流，也不会强制执行该政策。
async   false 已弃用 此属性已弃用。

示例

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

示例 1

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

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

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

示例 2

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

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

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

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值 不适用
是否必需？ 可选。如果省略 <DisplayName>，则会使用政策的 name 属性的值
Type 字符串
父元素 <PolicyElement>
子元素 无

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

语法

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

示例

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

<DisplayName> 元素没有属性或子元素。

<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 name="Spike-Arrest-1">
  <Rate>12pm</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 政策会抛出一个错误。

 可选 不适用

<UseEffectiveCount>

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

语法

<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> 元素的属性：

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

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

  • true：MP 的峰值速率限制为 <Rate> 除以同一 Pod 中的当前 MP 数量。汇总上限是 共 <Rate> 页。动态添加（或移除）MP 时，它们各自的峰值 速率限制会提高（或降低），但总体限制会保持不变。
  • 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 的有效速率从 MP 数量从 4 减少到 2 时，介于 10 到 20 之间。

流变量

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

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

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

错误参考信息

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

运行时错误

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

故障代码 HTTP 状态 原因 修复
policies.ratelimit.FailedToResolveSpikeArrestRate 500 如果对 <Rate> 元素中包含 rate 设置的变量的引用无法解析为 Spike Arrest 政策中的值，则会出现此错误。此元素是必需的，以 intpm 或 intps 的形式指定 Spike Arrest 速率。
policies.ratelimit.InvalidMessageWeight 500 如果通过流变量为 <MessageWeight> 元素指定的值无效（非整数值），就会出现此错误。
policies.ratelimit.SpikeArrestViolation 429

已超出速率限制。

<ph type="x-smartling-placeholder">

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因 修复
InvalidAllowedRate 如果 Spike Arrest 政策的 <Rate> 元素中指定的 spike arrest 速率不是整数，或者该速率不提供 ps 或 pm 作为后缀，则 API 代理的部署将失败。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

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

错误响应示例

错误响应的示例如下所示：

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

故障规则示例

下面显示了用于处理 SpikeArrestViolation 故障的故障规则示例：

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

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

<ph type="x-smartling-placeholder">

例如：

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 提供了政策架构作为参考。

相关主题