本頁面由 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>`

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	選用設定。如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值
類型	字串
上層元素	<`PolicyElement`>
子元素	無

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

語法

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

範例

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

<DisplayName> 元素沒有屬性或子項元素。

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

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

錯誤參考資料

本節說明系統傳回的錯誤代碼和錯誤訊息，以及錯誤變數。這項政策觸發錯誤時，由 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 (內部伺服器錯誤)，請將使用以下函式將 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>

語法

範例

<Identifier>

語法

範例 1

<MessageWeight>

語法

範例 1

<Rate>

語法

範例 1

範例 2

<UseEffectiveCount>

語法

範例 1

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

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

`<SpikeArrest>` 個元素

`<DisplayName>`

`<Identifier>`

`<MessageWeight>`

`<Rate>`

`<UseEffectiveCount>`