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

SpikeArrest 政策

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

尖峰流量防範政策可透過 <Rate> 元素防範流量激增情形。這個元素會限制 API Proxy 處理並傳送到後端的要求數，以防範效能延遲和停機。

Spike Arrest 的運作方式

請將「Spike Arrest」視為一種一般防範流量遽增的做法，而非限制流量至特定要求數量的做法。API 和後端可以處理特定流量量，而尖峰流量防範政策有助於將流量平滑處理至您想要的一般量。

執行階段的尖峰停止行為與您輸入的每分鐘或每秒值文字意義不同。

舉例來說，假設您輸入的頻率為 30pm (每分鐘 30 個要求)。在測試期間，您可能會認為只要在 1 分鐘內，就能在 1 秒內傳送 30 個要求。但這並非政策強制執行設定的方式。在某些環境中，1 秒內有 30 項要求可能會被視為小型尖峰。

那麼實際上會發生什麼事？為避免出現尖峰流量，尖峰流量防範會將設定分割成較短的間隔，以平滑允許的完整要求數量：

每分鐘的費率會以秒為間隔，平滑轉換為允許的完整要求。

舉例來說，30pm 會經過平滑處理，如下所示：
60 秒 (1 分鐘) / 30pm = 2 秒間隔，也就是每 2 秒允許 1 次要求。2 秒內的第二個要求會失敗。此外，一分鐘內的第 31 次要求也會失敗。
每秒的速率會以毫秒為間隔，平滑轉換為允許的完整要求。
舉例來說，10ps 會經過以下平滑處理：
1000 毫秒 (1 秒) / 10ps = 100 毫秒間隔，也就是每隔 100 毫秒允許 1 個要求。在 100 毫秒內提出的第二項要求會失敗。此外，一秒內的第 11 個要求也會失敗。

還有更多：1 個要求 * 訊息處理器數量

根據預設，除非您啟用 <UseEffectiveCount>，否則系統不會分發 Spike Arrest。也就是說，請求計數不會在各 MP 之間同步。當有多個訊息處理器 (尤其是採用輪替配置的處理器) 時，每個處理器都會獨立處理自己的尖峰抑制節流。使用一個訊息處理器時，30pm 的頻率可將流量平滑化，每 2 秒處理 1 次要求 (60 / 30)。如果使用兩個訊息處理器 (Edge 雲端的預設值)，則這個數字會加倍，變成每 2 秒 2 個要求。因此，請將每個間隔內計算出的完整要求數量乘以訊息處理器數量，即可算出整體逮捕率。

尖峰流量偵測和配額之間的差異

配額政策會設定用戶端應用程式在 1 小時、1 天、1 週或 1 個月內，可向 API 提交的要求訊息數量。配額政策會維持可計算傳入要求的散發計數器，藉此對用戶端應用程式強制執行用量限制。

請使用配額功能，與開發人員和合作夥伴簽訂商業合約或服務水準協議，而非用於管理營運流量。使用 Spike Arrest 防範 API 流量突然激增的情況。另請參閱「比較配額、尖峰封鎖和並發頻率限制政策」。

影片

以下影片說明如何使用尖峰流量防範政策，保護 API 免受流量尖峰影響：

這項功能的重要性

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

`<SpikeArrest>` 元素

定義尖峰流量防範政策。

預設值	請參閱下方的「Default Policy」分頁
是否必要？	選用
類型	複雜物件
上層元素	n/a
子元素	`<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>

此元素在所有政策中皆包含下列屬性：

屬性	預設	必填與否	Description
`name`	無	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個字元。或者，您也可以使用 `<DisplayName>` 元素，在管理 UI Proxy 編輯器中，以不同的自然語言名稱來標示政策。
`continueOnError`	false	選填	如果設為「false」，當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」，則在政策失敗後，仍會繼續執行流程。
`enabled`	true	選填	設為「true」即可強制執行政策。將政策設為「false」，即可「關閉」政策。即使政策已附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	這項屬性已淘汰。

範例

以下範例說明如何使用「尖峰流量偵測」政策：

範例 1

以下範例將速率設為每秒五次：

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

有效費率為 300pm，也就是說，每 200 毫秒就會在值區中新增一個符記。值區大小一律設為 messagesPerPeriod 的 10%。因此，如果 messagesPerPeriod 為 300，值區大小就是 30 個符記。

範例 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 代理程式中的所有要求強制執行一個速率限制。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<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 政策或指派訊息政策設定自訂變數。	不適用	必填

以下 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 的權重提交要求，則該用戶端每分鐘只能傳送五則訊息，因為每則要求都會計為 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

以下範例將速率設為每秒五次要求：

<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 Proxy 的速率為所有用戶端每分鐘 1 次要求。如果用戶端傳遞「custom_rate」標頭，則 Proxy 上所有用戶端的速率限制將變為每秒 10 個要求，直到傳送不含「custom_rate」標頭的要求為止。您可以使用 `<Identifier>` 將要求分組，為不同類型的用戶端強制套用自訂費率。如果您指定 `ref` 的值，但未在 `<Rate>` 元素的內容中設定費率，且用戶端未傳遞值，則「尖峰流量截斷」政策會擲回錯誤。	選用	不適用

ref

找出指定費率的流程變數。這可以是任何流程變數，例如 HTTP 查詢參數、標頭、訊息主體內容，或是 KVM 等值。詳情請參閱「流程變數參考資料」。

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

如果您同時定義 ref 和此元素的主體，系統會套用 ref 的值，並在要求中設定流程變數時優先採用該值。(如果 ref 中指定的變數「未」設於要求中，則反之亦然)。

例如：

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

在這個範例中，如果用戶端「未」傳遞「custom_rate」標頭，則 API Proxy 的速率為所有用戶端每分鐘 1 次要求。如果用戶端傳遞「custom_rate」標頭，則 Proxy 上所有用戶端的速率限制將變為每秒 10 個要求，直到傳送不含「custom_rate」標頭的要求為止。

您可以使用 <Identifier> 將要求分組，為不同類型的用戶端強制套用自訂費率。

如果您指定 ref 的值，但未在 <Rate> 元素的內容中設定費率，且用戶端未傳遞值，則「尖峰流量截斷」政策會擲回錯誤。

選用

不適用

`<UseEffectiveCount>`

使用自動調度群組時，會將 Spike Arrest 計數分散至各個 Message Processor (MP)。

注意：<UseEffectiveCount> 元素適用於 Edge 公用雲端和 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> 元素為選用元素。如果在 Spike Arrest 政策中省略此元素，預設值為 false。

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

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<SpikeArrest>`
子元素	無

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

屬性	說明	預設	存在必要性
`ref`	識別含有 `<UseEffectiveCount>` 值的變數。這可以是任何流程變數，例如 HTTP 查詢參數、標頭或訊息主體內容。詳情請參閱「流程變數參考資料」。您也可以使用 JavaScript 政策或 AssignMessage 政策設定自訂變數。	不適用	選用

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

true：MP 的尖峰速率限制是 <Rate> 除以同一個 pod 中目前的 MP 數量。匯總限制是 <Rate> 的值。當動態新增 (或移除) MPS 時，個別尖峰速率限制會增加 (或減少)，但總計限制會維持不變。
false (如果省略，則為預設值)：每個 MP 的尖峰速率限制，就是其 <Rate> 的值。總上限是所有 MP 費率的總和。新增 (或移除) 多個 MP 時，個別的尖峰率限制會維持不變，但總計限制會增加 (或減少)。

下表顯示 <UseEffectiveCount> 對各 MP 有效費率限制的影響：

	`<UseEffectiveCount>` 的值
	`false`	`false`	`false`	`true`	`true`	`true`
議員人數	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> 設為目標匯總限制。

流程變數

執行尖峰流量防範政策時，系統會填入下列流程變數：

變數	類型	權限	說明
`ratelimit.policy_name.failed`	布林值	唯讀	指出政策是否失敗 (`true` 或 `false`)。

詳情請參閱流程變數參考資料。

錯誤參考資料

本節說明系統傳回的錯誤代碼和錯誤訊息，以及錯誤變數。這項政策觸發錯誤時，由 Edge 設定的。請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則，處理錯誤詳情請參閱：注意事項瞭解政策錯誤和處理方式發生錯誤

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤程式碼	HTTP 狀態	原因
`policies.ratelimit.FailedToResolveSpikeArrestRate`	`500`	如果參照包含費率設定的變數，就會發生這個錯誤無法將 `<Rate>` 元素中的值解析為尖峰時段中的某個值政策。此為必要元素，可用來指定格式為 `intpm` 或 `intps`。
`policies.ratelimit.InvalidMessageWeight`	`500`	如果透過以下其中一種方式為 `<MessageWeight>` 元素指定值，就會發生這項錯誤。流量變數無效 (非整數值)。
`policies.ratelimit.SpikeArrestViolation`	`429`	超過頻率限制。注意：以 Private Cloud 來說，傳回的預設 HTTP 狀態碼為 `500`。如要變更傳回至 `429` 的狀態碼，請使用 API 設定這個屬性呼叫 (錯誤規則範例)

部署錯誤

當您部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因	修正
`InvalidAllowedRate`	如果在尖峰峰頂攻擊的 `<Rate>` 元素中指定峰值逮捕率政策不是整數。如果費率沒有「`ps`」或「`pm`」做為後置字串，那麼 API Proxy 的部署作業就會失敗

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知政策錯誤。

變數	地點	範例
`fault.name="fault_name"`	`fault_name` 是錯誤的名稱，如上方的「執行階段錯誤」表格。錯誤名稱是最後一部分錯誤程式碼	`fault.name Matches "SpikeArrestViolation"`
`ratelimit.policy_name.failed`	`policy_name` 是使用者指定錯誤的政策名稱。	`ratelimit.SA-SpikeArrestPolicy.failed = true`

錯誤回應範例

錯誤回應範例如下：

注意：如要處理錯誤，最佳做法是將錯誤回應的 errorcode 部分。請勿參考 faultstring，因為可能會有所變更。

{  
   "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 (內部伺服器錯誤)，請使用 Update organization properties 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 個要求 * 訊息處理器數量

尖峰流量偵測和配額之間的差異

影片

這項功能的重要性

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

<SpikeArrest> 元素

語法

預設政策

範例

範例 1

範例 2

範例 3

示例 4

子元素參照

<DisplayName>

Syntax

Example

<Identifier>

語法

範例 1

<MessageWeight>

語法

範例 1

<Rate>

語法

範例 1

範例 2

<UseEffectiveCount>

語法

範例 1

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

`<SpikeArrest>` 元素

`<DisplayName>`

`<Identifier>`

`<MessageWeight>`

`<Rate>`

`<UseEffectiveCount>`