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

SpikeArrest 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。資訊

「尖峰流量逮捕」政策能防範 <Rate> 元素流量激增。這個元素會限制 API Proxy 處理並傳送至後端的要求數量，以免發生效能延遲和停機。

史派克阿瑞斯特的運作原理

您可以將尖峰流量視為正常防範流量高峰的方法，而不是將流量限制在特定次數的途徑。您的 API 和後端可以處理特定流量，而尖峰流量防範政策可協助您將流量順利分配至所需的一般金額。

執行階段 Spike 逮捕行為與您輸入的每分鐘或每秒文字值不同。

舉例來說，假設您輸入了下午 30 點 (每分鐘 30 個要求) 的速率，在測試中，您可能會認為您可以在 1 秒內傳送 30 個要求，只要 1 分鐘內。不過，這並不是政策強制執行設定的方式。想想看，某些環境中的 1 秒內 30 個要求可能會是短暫的高峰。

實際上是怎麼了？為避免出現遽增的行為，「Spike Arrest 」會將您的設定分成較小的間隔，以便調節允許的完整要求數量：

每分鐘的取樣率會以秒為單位，達到允許的完整要求數。

舉例來說，下午 30 點可以使用以下方式順暢：
60 秒 (1 分鐘) / 30pm = 2 秒間隔，或每 2 秒允許 1 個要求。如果 2 秒內發生第二個要求，第二個要求就會失敗。此外，一分鐘內的第 31 項要求也會失敗。
每秒費率會平滑轉換為允許的完整要求，間隔為毫秒。
例如，10ps 會較為順暢：
1000 毫秒 (1 秒) / 10ps = 100 毫秒的間隔，或每 100 毫秒允許 1 個要求。如果 100 毫秒內的第二個要求會失敗，則會失敗。此外，第 11 次內的要求也會失敗。

還有 1 個要求 * 郵件處理器數量

根據預設，除非您啟用 <UseEffectiveCount>，否則系統不會分散尖峰流量。也就是說，要求數量不會跨 MP 同步處理。使用多個訊息處理器 (尤其是採用循環配置設定的機構)，每個訊息都會分別處理專屬的尖峰流量防範節流功能。透過單一訊息處理器，下午 30 點平穩地傳送每 2 秒 (60 / 30) 1 個要求的流量。如果有兩個訊息處理器 (Edge 雲端預設)，那麼這個數字每 2 秒將加倍至 2 次。因此，只要將每個間隔的完整要求數量乘以訊息處理器數量，即可得出整體逮捕率。

尖峰流量逮捕與配額之間的差異

配額政策可設定用戶端應用程式可在一小時、一天、一週或一個月內可提交至 API 的要求訊息數量。配額政策會透過維護會計算傳入要求的分散式計數器，來強制執行用戶端應用程式的用量限制。

使用配額來與開發人員和合作夥伴強制執行商業合約或服務水準協議，而非管理營運流量。使用 Spike 防範功能來防範 API 流量突然暴增。另請參閱比較配額、尖峰流量防範和並行頻率限制政策一文。

影片

下列影片說明如何使用「尖峰流量防範」政策，保護 API 不受流量激增的影響：

重要性

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

`<SpikeArrest>` 個元素

定義「高點逮捕」政策。

預設值	請參閱下方的「Default Policy」分頁
是否必填？	選用
類型	複雜物件
父項元素	不適用
子元素	`<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

以下範例將速率設定為每分鐘 12 次：

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

這個範例政策會將頻率調整為每五秒 (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>`

在管理 UI Proxy 編輯器中，除了 name 屬性，可用以其他自然更自然的名稱為政策加上標籤。

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

預設值	n/a
是否必填？	選用設定。如果省略 `<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 的要求都會強制執行一個頻率限制。

預設值	n/a
是否必填？	選用
類型	字串
父項元素	`<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 政策設定自訂變數。	n/a	必要

此外，以下 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。

預設值	n/a
是否必填？	選用
類型	整數
父項元素	`<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> 使用這個元素，透過接受用戶端的值，在執行階段平穩順暢地處理流量。

預設值	n/a
是否必填？	必要
類型	整數
父項元素	`<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 name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

這個範例政策會將頻率調整為每五秒 (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 上所有用戶端每秒 10 個要求，直到系統傳送不含「custom_rate」標頭的要求為止。您可以使用 `<Identifier>` 將要求分組，針對不同類型的用戶端強制執行自訂費率。如果您指定 `ref` 的值，但並未在 `<Rate>` 元素的主體中設定速率，且用戶端沒有傳遞值，則 Spike 逮捕政策會擲回錯誤。	選用	n/a

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 上所有用戶端每秒 10 個要求，直到系統傳送不含「custom_rate」標頭的要求為止。

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

如果您指定 ref 的值，但並未在 <Rate> 元素的主體中設定速率，且用戶端沒有傳遞值，則 Spike 逮捕政策會擲回錯誤。

選用

n/a

`<UseEffectiveCount>`

使用自動調整資源配置群組時，將高點逮捕次數分配到各個訊息處理器 (MP) 中。

注意：<UseEffectiveCount> 元素適用於 Edge Public Cloud，以及 Private Cloud 4.18.05 以上版本的 Edge。

語法

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

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

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

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

<UseEffectiveCount> 的影響取決於其值：

true：MP 的尖峰頻率限制是將 <Rate> 除以相同 Pod 中的目前 MP 數量。匯總限制為 <Rate> 的值。以動態方式新增 (或移除 MP) 時，個別尖峰頻率限制會提高 (或降低)，但匯總上限維持不變。
false (省略時的預設值)：每個 MP 的尖峰頻率限制就是其 <Rate> 的值。匯總限制是所有平台的比率總和。新增 (或移除 MP) 後，個別尖峰頻率限制將維持不變，但匯總上限會提高 (或降低)。

下表列出 <UseEffectiveCount> 對每 MP 有效頻率限制的影響：

	`<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 時，每 MP 的有效率從 4 降為 2，因此每 MP 的有效率會從 10 下降到 20。

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

流程變數

執行 Spike 逮捕政策時，系統會填入下列流程變數：

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

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

錯誤參考資料

本節說明這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

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

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤名稱	原因	修正
`InvalidAllowedRate`	如果尖峰流量防範政策的 `<Rate>` 元素中指定的尖峰逮捕率不是整數，或者費率沒有 `ps` 或 `pm` 做為後置字串，表示 API Proxy 部署作業會失敗。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables	地點	範例
`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 (內部伺服器錯誤)，請使用更新機構屬性 API，將 features.isHTTPStatusTooManyRequestEnabled 屬性設為 false。

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

史派克阿瑞斯特的運作原理

還有 1 個要求 * 郵件處理器數量

尖峰流量逮捕與配額之間的差異

影片

重要性

設定方式

附加政策

每秒頻率限制

每分鐘頻率限制

不重複頻率限制

比較配額政策

流程變數

<SpikeArrest> 個元素

語法

預設政策

範例

範例 1

範例 2

範例 3

示例 4

子項元素參照

<DisplayName>

語法

範例

<Identifier>

語法

範例 1

<MessageWeight>

語法

範例 1

<Rate>

語法

範例 1

範例 2

<UseEffectiveCount>

語法

範例 1

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

故障規則示例

結構定義

相關主題

`<SpikeArrest>` 個元素

`<DisplayName>`

`<Identifier>`

`<MessageWeight>`

`<Rate>`

`<UseEffectiveCount>`