您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
「尖峰流量逮捕」政策能防範 <Rate>
元素流量激增。這個元素會限制 API Proxy 處理並傳送至後端的要求數量,以免發生效能延遲和停機。
<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 |
無 | 必要 |
政策的內部名稱。 或者,您也可以使用 |
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 政策使用自訂變數。 如果您同時定義了這個元素的 例如: <Rate ref="request.header.custom_rate">1pm</Rate> 在此範例中,如果用戶端「不」傳遞「custom_rate」標頭,則 API Proxy 的速率為所有用戶端每分鐘要求 1 次。如果用戶端傳遞了「custom_rate」標頭,則頻率限制將成為 Proxy 上所有用戶端每秒 10 個要求,直到系統傳送不含「custom_rate」標頭的要求為止。 您可以使用 如果您指定 |
選用 | n/a |
<UseEffectiveCount>
使用自動調整資源配置群組時,將高點逮捕次數分配到各個訊息處理器 (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
。
預設值 | 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。
流程變數
執行 Spike 逮捕政策時,系統會填入下列流程變數:
變數 | 類型 | 權限 | 說明 |
---|---|---|---|
ratelimit.policy_name.failed |
布林值 | 唯讀 | 表示政策是否失敗 (true 或 false )。 |
詳情請參閱流程變數參考資料。
錯誤參考資料
本節說明這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
policies.ratelimit.FailedToResolveSpikeArrestRate |
500 |
如果參照的變數在 <Rate> 元素中包含費率設定的變數,並無法解析為「尖峰流量防範」政策中的值,就會發生這個錯誤。此為必要元素,用來以 intpm 或 intps 的格式指定尖峰時段逮捕率。 |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
如果透過流程變數為 <MessageWeight> 元素指定的值無效 (非整數值),就會發生這個錯誤。 |
build |
policies.ratelimit.SpikeArrestViolation |
429 |
超過頻率限制。 |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidAllowedRate |
如果尖峰流量防範政策的 <Rate> 元素中指定的尖峰逮捕率不是整數,或者費率沒有 ps 或 pm 做為後置字串,表示 API Proxy 部署作業會失敗。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
Variables | 地點 | 範例 |
---|---|---|
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
(內部伺服器錯誤),請使用
更新機構屬性 API,將 features.isHTTPStatusTooManyRequestEnabled
屬性設為 false
。
例如:
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 政策
- API Proxy 的執行範例