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

SpikeArrest 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

這項政策是標準政策，可部署至任何環境類型。如要瞭解政策類型和各環境類型的可用性，請參閱「政策類型」。

SpikeArrest 和 Quota 的差異

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

請使用配額功能，與開發人員和合作夥伴簽訂商業合約或服務水準協議，而非用於管理營運流量。使用 SpikeArrest 防範 API 流量突然暴增的情況。另請參閱「比較配額和 SpikeArrest 政策」。

影片

以下影片說明這項政策的用途：

這項功能的重要性

比較配額政策

`<SpikeArrest>` 元素

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

預設政策

以下範例顯示在 UI 中將 SpikeArrest 政策新增至流程時的預設設定：

<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>false</UseEffectiveCount>
</SpikeArrest>

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

範例

以下範例說明如何使用 SpikeArrest 政策：

範例 1

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

這項範例政策允許每秒最多 5 個要求。透過平滑處理，系統會將每 200 毫秒 (1000/5) 間隔的最大要求數量設為 1 個。

範例 2

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

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

這項範例政策允許每分鐘最多 12 個要求，也就是每 5 秒 (60/12) 間隔一個要求。如果 5 秒間隔內有超過一個要求，只要要求數量低於每分鐘 12 次的設定比率限制，系統就會允許這類要求 (不進行平滑處理)。

範例 3

以下範例會將要求限制為每分鐘 12 次 (每五秒一次，或 60/12)：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

此外，<MessageWeight> 元素會接受自訂值 (weight 標頭)，藉此調整特定應用程式或用戶端的訊息權重。這可讓您進一步控管使用 <Identifier> 元素識別的實體的節流。

範例 4

以下範例會指示 SpikeArrest 透過傳入的 request.header.runtime_rate 流程變數要求，尋找設定的執行階段值：

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</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>`

讓您選擇要求的群組方式，以便根據用戶端套用 SpikeArrest 政策。舉例來說，您可以依開發人員 ID 將要求分組，在這種情況下，每位開發人員的要求都會計入其 SpikeArrest 比率，而非所有對 Proxy 的要求。

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

如果您將 <Identifier> 元素留空，系統會對該 API 代理程式中的所有要求強制執行一個速率限制。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<SpikeArrest>`
子元素	無

語法

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

範例 1

以下範例會為每個開發人員 ID 套用 SpikeArrest 政策：

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

下表說明 <Identifier> 的屬性：

屬性	說明	預設	存在必要性
`ref`	指出 SpikeArrest 將傳入要求分組的變數。您可以使用任何流程變數來指示專屬客戶，例如可透過 VerifyAPIKey 政策取得的客戶。您也可以使用 JavaScript 政策或指派訊息政策設定自訂變數。	不適用	必填

這篇 Apigee 社群貼文也討論了這個元素。

`<MessageWeight>`

指定為每則訊息定義的權重。訊息權重會修改單一要求對 SpikeArrest 比率計算的影響。訊息權重可以是任何流量變數，例如 HTTP 標頭、查詢參數、表單參數或訊息主體內容。您也可以使用 JavaScript 政策或AssignMessage 政策來使用自訂變數。

搭配使用 <Identifier>，進一步依特定用戶端或應用程式限制要求。

舉例來說，如果 SpikeArrest <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" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

在此範例中，<MessageWeight> 會接受自訂值 (要求中的 weight 標頭)，藉此調整特定用戶端的訊息權重。這可讓您進一步控管使用 <Identifier> 元素識別的實體的節流。

下表說明 <MessageWeight> 的屬性：

屬性	說明	存在必要性	預設
`ref`	找出包含特定用戶端訊息權重的流程變數。這可以是任何流程變數，例如 HTTP 查詢參數、標頭或訊息主體內容。詳情請參閱流程變數參考資料。您也可以使用 JavaScript 政策或 AssignMessage 政策設定自訂變數。	必填	不適用

`<Rate>`

透過設定每分鐘或每秒間隔允許的要求次數，指定限制流量尖峰 (或爆量) 的頻率。您也可以搭配使用這個元素和 <Identifier> 和 <MessageWeight>，接受來自用戶端的值，以便在執行階段順利調節流量。使用 <UseEffectiveCount> 元素設定政策使用的速率限制演算法。

注意：任何 Apigee 機構或執行實際工作負載的 Apigee 混合機構，皆不支援使用 <UseEffectiveCount> 搭配值或 false。詳情請參閱 <UseEffectiveCount>。

如要瞭解可指定的最大速率限制，請參閱「限制」頁面的 SpikeArrest 部分。

預設值	不適用
是否必要？	必填
類型	整數
上層元素	`<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>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

這項政策會將頻率調降為每 200 毫秒 (1000/5) 允許一個要求。

範例 2

以下範例將頻率設為每分鐘 12 個要求：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</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>` 元素的內容中設定費率，且用戶端未傳遞值，則 SpikeArrest 政策會擲回錯誤。	選用	不適用

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> 元素的內容中設定費率，且用戶端未傳遞值，則 SpikeArrest 政策會擲回錯誤。

選用

不適用

`<UseEffectiveCount>`

您可以透過將值設為 true 或 false，選擇要使用哪種尖峰停止演算法，如下所述：

是

如果設為 true，SpikeArrest 會在區域中分散。這表示要求計數會在區域內的訊息處理器 (MP) 之間同步。此外，系統會採用「滑動視窗」頻率限制演算法。這個演算法可提供一致的速率限制行為，且不會「平滑」傳送至後端的傳入要求數量。如果在短時間間隔內傳送大量要求，只要要求數量不超過 <Rate> 元素中所設定的速率限制，系統就會允許這些要求。例如：

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

false (預設)

注意：雖然預設值為 false，但 Apigee 機構應將此元素設為 true。Apigee 機構不支援費率平滑處理。

您可以為 Apigee Hybrid 機構設定費率平滑處理功能，但必須以每個 Pod 為單位運作。混合式機構必須停用 Pod 調整功能，才能有效執行費率平滑處理作業，但這類做法不建議用於實際工作負載。

如果設為 false (預設值)，SpikeArrest 政策就會使用「權杖集區」演算法，將您指定的速率限制分割成較短的間隔，以平滑流量尖峰。這種做法的缺點是，在短時間內收到多項合法要求時，可能會遭到拒絕。

舉例來說，假設您輸入的頻率為 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 個要求也會失敗。

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

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

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

流程變數

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

屬性	類型	讀取/寫入	說明	範圍開始
ratelimit.`policy_name`.allowed.count	長	唯讀	傳回允許的配額數量。	PostClientFlow
ratelimit.`policy_name`.used.count	長	唯讀	傳回在配額間隔內目前使用的配額。	PostClientFlow
ratelimit.`policy_name`.available.count	長	唯讀	傳回配額間隔內的可用配額數量。	PostClientFlow
ratelimit.`policy_name`.exceed.count	長	唯讀	超過配額後會傳回 1。	PostClientFlow
ratelimit.`policy_name`.total.exceed.count	長	唯讀	超過配額後會傳回 1。	PostClientFlow
ratelimit.`policy_name`.expiry.time	長	唯讀	傳回世界標準時間 (以毫秒為單位)，用於決定配額到期時間和新配額間隔開始時間。如果配額政策的類型為 `rollingwindow`，這個值就無效，因為配額間隔不會到期。	PostClientFlow
ratelimit.`policy_name`.identifier	字串	唯讀	傳回附加至政策的 (用戶端) ID 參照	PostClientFlow
ratelimit.`policy_name`.class	字串	唯讀	傳回與用戶端 ID 相關聯的類別	PostClientFlow
ratelimit.`policy_name`.class.allowed.count	長	唯讀	傳回類別中定義的允許配額數量	PostClientFlow
ratelimit.`policy_name`.class.used.count	長	唯讀	傳回類別中已使用的配額	PostClientFlow
ratelimit.`policy_name`.class.available.count	長	唯讀	傳回類別中可用的配額數量	PostClientFlow
ratelimit.`policy_name`.class.exceed.count	長	唯讀	傳回目前配額間隔中，超出類別限制要求的數量	PostClientFlow
ratelimit.`policy_name`.class.total.exceed.count	長	唯讀	傳回在所有配額間隔中，超過類別上限要求的總數，也就是所有配額間隔的 `class.exceed.count` 總和。	PostClientFlow
ratelimit.`policy_name`.failed	布林值	唯讀	表示政策是否失敗 (true 或 false)。	PostClientFlow

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

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因
`policies.ratelimit.FailedToResolveSpikeArrestRate`	`500`	如果無法將 `<Rate>` 元素中含有費率設定的變數參照解析為 `SpikeArrest` 政策中的值，就會發生此錯誤。此元素為必填項目，用於以 `intpm` 或 `intps` 的形式指定尖峰偵測率。
`policies.ratelimit.InvalidMessageWeight`	`500`	如果透過流程變數為 `<MessageWeight>` 元素指定的值無效 (非整數值)，就會發生這個錯誤。
`policies.ratelimit.SpikeArrestViolation`	`429`	超過頻率限制。

部署錯誤

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

錯誤名稱	原因	修正
`InvalidAllowedRate`	如果 `SpikeArrest` 政策的 `<Rate>` 元素中指定的尖峰停止率不是整數，或是該率沒有使用 `ps` 或 `pm` 做為尾碼，則 API 代理程式會部署失敗。

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
`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>

目前，如果超出 Quota 或 SpikeArrest 政策設定的頻率限制，HTTP 狀態碼會為 429 (要求數超量)。

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

SpikeArrest 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

SpikeArrest 和 Quota 的差異

影片

這項功能的重要性

比較配額政策

<SpikeArrest> 元素

語法

預設政策

範例

範例 1

範例 2

範例 3

範例 4

子元素參照

<DisplayName>

語法

範例

<Identifier>

語法

範例 1

<MessageWeight>

語法

範例 1

<Rate>

語法

範例 1

範例 2

<UseEffectiveCount>

是

false (預設)

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

SpikeArrest 政策

`<SpikeArrest>` 元素

`<DisplayName>`

`<Identifier>`

`<MessageWeight>`

`<Rate>`

`<UseEffectiveCount>`