本頁面由 Cloud Translation API 翻譯而成。

SpikeArrest 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

使用 <Rate> 元素可防範流量激增的情況，這個元素限制了 API Proxy 處理並傳送至後端的要求數量。防止效能延遲和停機時間

《Spike Arrest》的運作方式

您可以把「尖峰時段攻擊」視為一般防範流量高峰，而非將流量限制於特定數量要求您的 API 和後端可處理和《尖峰峰政策》政策您期望的行為

執行階段 Spike Arrest 行為與您預期會出現的每分鐘或每秒輸入的值

例如，假設您輸入的費率是下午 30 點 (每分鐘 30 個要求)，在測試過程中您認為可以在一分鐘內傳送 30 個要求但政策並非強制執行設定的方式仔細想想， 1 秒內 30 個要求在某些環境中可以視為是小的高峰

然後呢？為了預防類似突然激增的行為，Spike Arrest 將數值記下來將設定分成更短的間隔：

每分鐘費率會流暢配合時間間隔內的完整要求數秒。

舉例來說，下午 30 點會經過平滑處理：
60 秒 (1 分鐘) / 30pm = 2 秒間隔，或每 2 秒允許 1 個要求。A 罩杯因此 2 秒內第二次的請求將會失敗。此外，在一分鐘內提出第 31 項要求失敗。
每秒比率會順暢化成一段時間內的完整要求毫秒。
例如，10 分的平滑效果會像這樣：
1000 毫秒 (1 秒) / 10ps = 100 毫秒間隔，或每 100 次允許 1 個要求毫秒。如果 100 毫秒內，第二次要求將會失敗。此外，在一秒內提出第 11 項要求失敗。

，瞭解如何調查及移除這項存取權。

還有其他要求：1 個要求 * 訊息處理器數量

根據預設，除非您啟用 <UseEffectiveCount>，否則系統不會分配 Spike Arrest。這代表要求數並未同步處理可以有效處理大量影片有多個訊息處理器，尤其是有循環機制訊息配置時，每個物件都會各自處理自己的 Spike Arrest 節流。包含一則訊息處理器，下午 30 點讓流量每 2 秒 (60 / 30) 能夠順暢處理到 1 個要求。包含兩則訊息處理器 (Edge 雲端的預設值)，該數字每 2 秒會倍增為 2 個要求。以下內容將計算出的完整要求數乘以訊息處理器數量進而得知自己的整體逮捕率

高點與低點之間的差異逮捕和配額

配額政策可設定用戶端應用程式允許的要求訊息數量每小時、每天、每週或每月提交一次 API。配額政策會強制執行用戶端應用程式的用量限制，方法是維護用於計算傳入流量的分散式計數器要求。

使用配額，讓開發人員和合作夥伴能夠履行業務合約或服務水準協議，而非而不是營運流量管理使用 Spike Arrest 防範 API 突然遽增流量另請參閱比較配額、尖峰攻擊和並行頻率限制政策。

影片

這些影片將說明如何運用「尖峰尖峰心」計畫，防範 API 遭受流量高峰政策：

為什麼需要

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

`<SpikeArrest>` 個元素

定義尖峰流量防範政策。

預設值	請參閱下方的預設政策分頁
是否必填？	選用
類型	複合式園區物體
父項元素	不適用
子元素	`<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 UI 中的流程：

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

範例

以下範例說明使用「暴雨逮捕」政策的部分方式：

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

此範例政策會將速率平滑處理每五項要求 seconds (60/12)。

範例 3

以下範例會將要求限制為每分鐘 12 次 (每五項要求允許一個要求) 秒或 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>`

讓您選擇要求的分組方式，以便根據何者套用尖峰流量政策呼叫。舉例來說，您可以按開發人員 ID 將要求分組，開發人員的要求將計入自己的「尖峰尖峰心」率，而非所有傳送至 Proxy 上。

與 <MessageWeight> 元素搭配使用，更精細控管要求節流

如果將 <Identifier> 元素留空，系統會針對所有要求強制執行一項頻率限制傳送至該 API Proxy

預設值	不適用
是否必填？	選用
類型	字串
父項元素	`<SpikeArrest>`
子元素	無

語法

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

範例 1

以下範例為每個開發人員 ID 套用尖峰流量防範政策：

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

下表說明 <Identifier> 的屬性：

屬性	說明	預設	存在必要性
`ref`	找出 Spike Arrest 將傳入要求分組的變數，您可以使用任何流程變數來表示不重複的用戶端，例如與 VerifyAPIKey 政策。您也可以使用 JavaScript 政策或 AssignMessage 政策。	不適用	必填

此外，也會在以下 Apigee 社群文章中討論這項元素：http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html。

`<MessageWeight>`

指定每則訊息定義的權重。訊息權重改變了影響只處理單一要求的尖峰期攻擊率訊息權重可以是任何值流程變數，例如 HTTP 標頭、查詢參數、表單參數或郵件內文。您也可以使用 JavaScript 政策或 AssignMessage 政策。

與 <Identifier> 搭配使用，可特定用戶端或應用程式

舉例來說，如果峰值尖峰 <Rate> 為 10pm，而應用程式提交了權重為 2 的要求，之後每分鐘只會有 5 則訊息因為每個要求會計為 2 次。

預設值	不適用
是否必填？	選用
類型	整數
父項元素	`<SpikeArrest>`
子元素	無

語法

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

範例 1

以下範例會將要求限制為每分鐘 12 次 (每五項要求允許一個要求) 秒或 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>

此範例政策會將速率平滑處理每五項要求 seconds (60/12)。

下表說明 <Rate> 的屬性：

屬性說明存在必要性預設

屬性	說明	存在必要性	預設
`ref`	識別指定速率的流程變數。可以是任何流程變數，例如 HTTP 查詢參數、標頭或郵件內文或值例如 KVM詳情請參閱流程變數參考資料。你也可以使用自訂變數使用 JavaScript 政策或 AssignMessage 政策。如果您同時定義 `ref` 和這個元素的主體，套用 `ref` 的值，並在資料流變數發生時優先採用使用物件規則(如果 `ref` 中找出的變數，則反轉為 true 要求中「未」設定)。例如： <Rate ref="request.header.custom_rate">1pm</Rate> 在本例中，如果用戶端「未」傳送「custom_rate」然後是標頭所有用戶端的 API Proxy 頻率為每分鐘 1 個要求。如果用戶端將「custom_rate」標頭，那麼針對 Proxy 存取，直到回應不含「custom_rate」的要求標頭。您可以使用 `<Identifier>` 將要求分組，強制針對以下項目套用自訂費率：不同類型的用戶端如果您指定 `ref` 的值，但未在 `<Rate>` 元素，而用戶端未傳遞值，然後是「暴增逮捕」政策擲回錯誤。	選用	不適用

ref

識別指定速率的流程變數。可以是任何流程變數，例如 HTTP 查詢參數、標頭或郵件內文或值例如 KVM詳情請參閱流程變數參考資料。

你也可以使用自訂變數使用 JavaScript 政策或 AssignMessage 政策。

如果您同時定義 ref 和這個元素的主體，套用 ref 的值，並在資料流變數發生時優先採用使用物件規則(如果 ref 中找出的變數，則反轉為 true 要求中「未」設定)。

例如：

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

在本例中，如果用戶端「未」傳送「custom_rate」然後是標頭所有用戶端的 API Proxy 頻率為每分鐘 1 個要求。如果用戶端將「custom_rate」標頭，那麼針對 Proxy 存取，直到回應不含「custom_rate」的要求標頭。

您可以使用 <Identifier> 將要求分組，強制針對以下項目套用自訂費率：不同類型的用戶端

如果您指定 ref 的值，但未在 <Rate> 元素，而用戶端未傳遞值，然後是「暴增逮捕」政策擲回錯誤。

選用

不適用

`<UseEffectiveCount>`

使用自動調整資源配置功能時，將尖峰通知平均分配給訊息處理器 (MP) 群組。

注意：<UseEffectiveCount> 元素適用於 Edge Public Cloud 和 Edge 版的私有雲 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。就會觸發這個事件。

注意：<UseEffectiveCount> 元素包含在預設的 SpikeArrest 政策中並設為 true。

預設值	否
是否必填？	選用
類型	布林值
父項元素	`<SpikeArrest>`
子元素	無

下表將說明 <UseEffectiveCount> 元素的屬性：

屬性	說明	預設	存在必要性
`ref`	識別包含 `<UseEffectiveCount>` 值的變數。可用的值包括任何流程變數，例如 HTTP 查詢參數、標頭或郵件內文內容。如要請參閱流程變數參考資料。您也可以設定自訂變數使用 JavaScript 政策或 AssignMessage 政策。	不適用	選用

<UseEffectiveCount> 的效果取決於其值：

true：MP 的峰值頻率限制是指 <Rate> 除以同一廣告連播中的目前百萬像素數量。匯總限制是指 (共 <Rate> 個)。動態增加 (或移除) 營利成效會個別激增頻率限制將會提高 (或降低)，但匯總限制則維持不變。
false (省略時此為預設值)：每百萬次觀看頻率的高峰頻率限制為就是其 <Rate> 的值。匯總限量是指所有百萬像素比率的總和。增加 (或移除) 營利模式時各自的高點頻率限制將維持不變，但匯總上限則會提高 ( 減少)。

下表列出 <UseEffectiveCount> 對有效頻率限制：

	`<UseEffectiveCount>` 的值
	`false`	`false`	`false`	`true`	`true`	`true`
百萬像素數	8	4	2	8	4	2
`<Rate>` 的值	10	10	10	40	40	40
每百萬像素效益	10	10	10	5	10	20
匯總限制	80	40	20	40*	40*	40*
* 與 `<Rate>` 相同。

請注意，在這個例子中，MP 授權數從 4 減少為 2 <UseEffectiveCount>為 false，每 MP 平均費率仍相同 ( 10)。但當 <UseEffectiveCount> 為 true 時，每百萬像素的實際費率是百萬像素數量從 4 人減少至 20 時，則設為 10 至 20 人。

提示：將 <UseEffectiveCount> 設為 true，請將 <Rate> 設為目標匯總限制。

流程變數

執行 Spike 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>

超過配額或尖峰流量政策設定的頻率限制時，適用的 HTTP 狀態碼為 429 (「要求數超量」)。如何將 HTTP 狀態碼變更為 500 (內部伺服器錯誤)，請將使用以下函式將 features.isHTTPStatusTooManyRequestEnabled 資源加到 false 更新機構屬性 API。

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 個要求 * 訊息處理器數量

高點與低點之間的差異 逮捕和配額

影片

為什麼需要

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

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