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

結果
您可以使用配額政策,設定 API Proxy 在一段時間內 (例如 1 分鐘、1 小時、1 天、1 週或 1 個月) 允許的要求訊息數量。您可以為所有存取 API 代理程式的應用程式設定相同的配額,也可以根據下列項目設定配額:
- 包含 API Proxy 的產品
- 要求 API 的應用程式
- 應用程式開發人員
- 許多其他條件
請勿使用配額來防範整體流量激增情形。請使用 SpikeArrest 政策。請參閱「尖峰流量防範政策」。
影片
以下影片介紹配額政策的配額管理功能:
簡介 (新 Edge)
簡介 (傳統 Edge)
動態配額
分散式與同步
訊息重量
日曆
滾動週期
Flexi
條件式配額
流程變數
處理錯誤
範例
以下政策程式碼範例說明如何透過以下方式開始和結束配額期間:
動態配額增加
<Quota name="CheckQuota"> <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval> <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit> <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/> </Quota>
動態配額可讓您設定單一配額政策,根據傳遞至配額政策的資訊,強制執行不同的配額設定。在這個情況下,配額設定的另一個名稱是「服務方案」。動態配額會檢查應用程式的「服務方案」,然後強制執行這些設定。
注意:如果您同時為元素指定值和參照,則參照會獲得優先順序。如果參照項目在執行階段未解析,則會使用該值。
舉例來說,建立 API 產品時,您可以選擇設定允許的配額限制、時間單位和間隔。不過,在 API 產品上設定這些值,並不會強制在 API Proxy 中使用這些值。您也必須在讀取這些值的 API 代理程式中新增配額政策。詳情請參閱「建立 API 產品」。
在上述範例中,包含配額政策的 API Proxy 會使用名為 verify-api-key
的 VerifyAPIKey 政策,驗證要求中傳遞的 API 金鑰。接著,配額政策會存取來自 VerifyAPIKey 政策的流程變數,讀取在 API 產品上設定的配額值。如要進一步瞭解 VerifyAPIKey 流程變數,請參閱「Verify API Key 政策」。
另一個選項是為個別開發人員或應用程式設定自訂屬性,然後在配額政策中讀取這些值。舉例來說,您想為每位開發人員設定不同的配額值。在這種情況下,您會為開發人員設定自訂屬性,其中包含限制、時間單位和間隔。接著,您可以在配額政策中參照這些值,如下所示:
<Quota name="DeveloperQuota"> <Identifier ref="verifyapikey.verify-api-key.client_id"/> <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> </Quota>
這個範例也會使用 VerifyAPIKey 流程變數,參照開發人員設定的自訂屬性。
您可以使用任何變數設定配額政策的參數。這些變數可能來自:
- 流程變數
- API 產品、應用程式或開發人員的屬性
- 鍵/值對應 (KVM)
- 標頭、查詢參數、表單參數等
針對每個 API proxy,您可以新增配額政策,讓該政策參照與所有其他 proxy 中的其他配額政策相同的變數,或是讓配額政策參照該政策和 proxy 專屬的變數。
開始時間
<Quota name="QuotaPolicy" type="calendar"> <StartTime>2017-02-18 10:30:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
如果配額的 type
設為 calendar
,您必須定義明確的 <StartTime>
值。時間值是世界標準時間,而非當地時間。如果您未為 calendar
類型的政策提供 <StartTime>
值,Edge 會發出錯誤。
每個應用程式的配額計數器會根據 <StartTime>
、<Interval>
和 <TimeUnit>
值進行重新整理。在這個範例中,配額會從 2017 年 2 月 18 日格林威治標準時間上午 10 點 30 分開始計算,且每 5 小時重新整理一次。因此,下次更新時間為 2017 年 2 月 18 日下午 3 點 30 分 (格林威治標準時間)。
存取計數器
<Quota name="QuotaPolicy"> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
API Proxy 可存取由配額政策設定的流量變數。您可以在 API 代理程式中存取這些流程變數,以便執行條件處理作業、監控政策是否接近配額限制、將目前的配額計數器傳回應用程式,或執行其他操作。
由於政策的流程變數存取權取決於政策的 name
屬性,因此對於上述名為 QuotaPolicy
的政策,您可以透過以下格式存取其流程變數:
ratelimit.QuotaPolicy.allowed.count
:允許的計數。ratelimit.QuotaPolicy.used.count
:目前的計數器值。ratelimit.QuotaPolicy.expiry.time
:計數器重設時的世界協調時間。
您可以存取許多其他流程變數,如下所述。
例如,您可以使用下列 AssignMessage 政策,將配額流量變數的值做為回應標頭傳回:
<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars"> <AssignTo createNew="false" type="response"/> <Set> <Headers> <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header> <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header> <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
第一項要求
<Quota name="MyQuota"> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> <Allow count="10000"/> </Quota>
使用這個範例程式碼,強制執行每小時 10,000 個呼叫的配額。這項政策會在每小時的整點重設配額計數器。如果計數器在小時結束前就達到 10,000 通話配額,系統會拒絕超過 10,000 通話的呼叫。
舉例來說,如果計數器從 2017-07-08 07:00:00
開始,則會在 2017-07-08 08:00:00
(從開始時間算起 1 小時) 重設為 0。如果第一則訊息是在 2017-07-08 07:35:28
收到,且訊息計數在 2017-07-08 08:00:00
前達到 10,000 則,系統會拒絕超過該計數的呼叫,直到計數在小時初始時重設為止。
計數器重設時間會根據 <Interval>
和 <TimeUnit>
的組合而定。舉例來說,如果您將 <Interval>
設為 <TimeUnit>
的 12,則計數器會每 12 小時重設一次。您可以將 <TimeUnit>
設為分鐘、小時、天、週或月。
您可以在 API Proxy 的多個位置參照這項政策。舉例來說,您可以將其放在 Proxy PreFlow 上,以便在每項要求上執行。或者,您也可以將其放在 API Proxy 中的多個資料流上。如果您在 Proxy 的多個位置使用這項政策,系統會維護單一計數器,並由政策的所有例項更新。
或者,您也可以在 API Proxy 中定義多個配額政策。每個配額政策都會根據政策的 name
屬性維護專屬計數器。
設定 ID
<Quota name="QuotaPolicy" type="calendar"> <Identifier ref="request.header.clientId"/> <StartTime>2017-02-18 10:00:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
根據預設,無論要求來源為何,配額政策都會為 API Proxy 定義單一計數器。或者,您也可以搭配使用 <Identifier>
屬性和配額政策,根據 <Identifier>
屬性的值維護個別計數器。
舉例來說,您可以使用 <Identifier>
標記為每個用戶端 ID 定義個別計數器。在對 Proxy 提出要求時,用戶端應用程式會傳遞包含 clientID
的標頭,如上例所示。
您可以將任何流程變數指定給 <Identifier>
屬性。舉例來說,您可以指定名為 id
的查詢參數包含專屬 ID:
<Identifier ref="request.queryparam.id"/>
如果您使用的是 VerifyAPIKey 政策來驗證 API 金鑰,或是 OAuth 權杖的 OAuthV2 政策,則可以使用 API 金鑰或權杖中的資訊,為相同的配額政策定義個別計數器。舉例來說,下列 <Identifier>
代碼會使用名為 verify-api-key
的 VerifyAPIKey 政策的 client_id
流程變數:
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
每個不重複的 client_id
值現在都會在配額政策中定義專屬計數器。
類別
<Quota name="QuotaPolicy"> <Interval>1</Interval> <TimeUnit>day</TimeUnit> <Allow> <Class ref="request.header.developer_segment"> <Allow class="platinum" count="10000"/> <Allow class="silver" count="1000" /> </Class> </Allow> </Quota>
您可以使用以類別為基礎的配額計數,動態設定配額限制。在這個範例中,配額限制取決於每項要求傳遞的 developer_segment
標頭值。該變數的值可以是 platinum
或 silver
。如果標頭含有無效值,政策會傳回配額違規錯誤。
關於配額政策
配額是 API Proxy 可在一段時間內 (例如分鐘、小時、日、週或月) 處理的要求訊息配額。政策會維護計數器,用於計算 API Proxy 收到的要求數量。這項功能可讓 API 供應器在一段時間內,強制限制應用程式發出的 API 呼叫次數。例如,您可以使用配額政策限制應用程式每分鐘提出 1 次要求,或每月提出 10,000 次要求。
舉例來說,如果配額定義為每月 10,000 則郵件,則會在第 10,000 則郵件後開始實施速率限制。無論是第一天還是該週期的最後一天,只要有 10,000 則訊息,系統就會自動重設配額計數器,直到指定時間間隔結束為止。如果您想在指定時間間隔結束前,就允許額外要求,則必須使用重設配額政策明確重設配額。
配額的變化版本「SpikeArrest」可防止因用量突然增加、用戶端發生錯誤或遭受惡意攻擊而導致的流量尖峰 (或爆量)。如要進一步瞭解 SpikeArrest,請參閱「尖峰流量防範政策」。
配額適用於個別 API Proxy,不會在 API Proxy 之間分配。舉例來說,如果 API 產品中有三個 API Proxy,即使三者都使用相同的配額政策設定,也不會共用單一配額。
配額政策類型
配額政策支援多種不同類型的政策:預設、calendar
、flexi
和 rollingwindow
。每個類型都會定義配額計數器的啟動和重設時間,如下表所示:
時間單位 | 預設 (或空值) 重設 | 日曆重設 | flexi 重設 |
---|---|---|---|
分鐘 | 下一分鐘的開始 | <StartTime> 後 1 分鐘 |
第一項要求後一分鐘 |
小時 | 下一個小時的開頭 | <StartTime> 後一小時 |
第一項要求後一小時 |
天 | 當天午夜 (格林威治標準時間) | <StartTime> 後 24 小時 |
首次要求後 24 小時 |
週 | 週末的格林威治標準時間凌晨 12 點 | <StartTime> 過後一週 |
首次要求後一週 |
個月 | 當月最後一天的格林威治標準時間午夜 | <StartTime> 過後一個月 (28 天) |
首次提出要求後一個月 (28 天) |
對於 type="calendar"
,您必須指定 <StartTime>
的值。
表格未列出 rollingwindow
類型的值。滾動式視窗配額的運作方式是設定配額「視窗」的大小,例如一小時或一天的視窗。收到新要求時,政策會判斷是否在過去的「時間間隔」內超出配額。
舉例來說,您可以定義兩小時的時間窗,允許 1000 個要求。新的要求會在下午 4 點 45 分進來。政策會計算過去兩小時的配額計數,也就是下午 2 點 45 分後的要求次數。如果在兩小時內未超過配額上限,系統就會允許要求。
一分鐘後,即下午 4 點 46 分,另一個要求傳入。政策現在會計算下午 2 點 46 分以後的配額計數,判斷是否已超過上限。
對於 rollingwindow
類型,計數器不會重設,但會在每次要求時重新計算。
瞭解配額計數器
根據預設,無論您在 API Proxy 中參照配額政策的次數為何,該政策都會維持單一計數器。配額計數器的名稱會根據政策的 name
屬性。
舉例來說,您可以建立名為 MyQuotaPolicy
的配額政策,並將其設為 5 個要求的限制,然後將其放在 API Proxy 中的多個流程中 (流程 A、B 和 C)。即使在多個流程中使用,它仍會維護單一計數器,並由政策的所有執行個體更新:
- 執行流程 A -> 執行 MyQuotaPolicy,計數器 = 1
- 執行流程 B -> 執行 MyQuotaPolicy,其計數器 = 2
- 執行流程 A -> 執行 MyQuotaPolicy,計數器 = 3
- 執行流程 C -> 執行 MyQuotaPolicy,其計數器 = 4
- 執行流程 A -> 執行 MyQuotaPolicy,計數器 = 5
配額計數器已達上限,因此對任何三個流程的下一個要求都會遭到拒絕。
在 API Proxy 流程中的多個位置使用相同的配額政策,可能會導致配額比預期更快用盡,這也是 Apigee Edge 反模式手冊中所述的反模式。
或者,您也可以在 API Proxy 中定義多個配額政策,並在每個流程中使用不同的政策。每個配額政策都會根據政策的 name
屬性維護專屬計數器。
或者,您也可以在配額政策中使用 <Class>
或 <Identifier>
元素,在單一政策中定義多個不重複的計數器。透過這些元素,單一政策可根據提出要求的應用程式、提出要求的應用程式開發人員、用戶端 ID 或其他用戶端 ID 等,維護不同的計數器。如要進一步瞭解如何使用 <Class>
或 <Identifier>
元素,請參閱上述範例。
時間標記
所有配額時間都設為世界標準時間 (UTC) 時區。
配額時間符號遵循國際標準 ISO 8601 中定義的國際標準日期符號。
日期的定義為年、月和日,格式如下:YYYY-MM-DD
。例如,2015-02-04
代表 2015 年 2 月 4 日。
時間定義為小時、分鐘和秒,格式如下:hours:minutes:seconds
。舉例來說,23:59:59
代表午夜前 1 秒的時間。
請注意,00:00:00
和 24:00:00
這兩種符號可用於區分可與某一日期相關聯的兩個午夜。因此,2015-02-04
24:00:00
與 2015-02-05 00:00:00
的日期和時間相同。後者通常是較佳的符號。
從 API 產品設定取得配額設定
您可以在 API 產品設定中設定配額上限。這些限制不會自動強制執行配額。您可以改為在配額政策中參照產品配額設定。以下是為產品設定配額以供配額政策參考的優點:
- 配額政策可在 API 產品中的所有 API Proxy 中使用一致的設定。
- 您可以對 API 產品的配額設定進行執行階段變更,而參照該值的配額政策也會自動更新配額值。
如要進一步瞭解如何使用 API 產品的配額設定,請參閱上方的「動態配額」範例。
如要瞭解如何設定配額限制的 API 產品,請參閱「建立 API 產品」一文。
元素參照
以下是您可以在這項政策中設定的元素和屬性。請注意,某些元素組合互斥或不必要。請參閱特定用途的範例。當您使用名為「VerifyAPIKey」的「驗證 API 金鑰」政策,在要求中檢查應用程式的 API 金鑰時,系統會預設使用下方的 verifyapikey.VerifyAPIKey.apiproduct.*
變數。變數值來自金鑰所關聯的 API 產品的配額設定,如「從 API 產品設定取得配額設定」一文所述。
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar"> <DisplayName>Quota 3</DisplayName> <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> <Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow> <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit> <StartTime>2017-7-16 12:00:00</StartTime> <Distributed>false</Distributed> <Synchronous>false</ Synchronous> <AsynchronousConfiguration> <SyncIntervalInSeconds>20</ SyncIntervalInSeconds> <SyncMessageCount>5</ SyncMessageCount> </AsynchronousConfiguration> <Identifier/> <MessageWeight/> </Quota>
<Quota> 屬性
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
下列屬性僅適用於這項政策。
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
類型 |
用於決定配額計數器檢查配額用量的時間和方式。詳情請參閱「配額政策類型」。 如果省略 有效值包括:
|
日曆 | 選用 |
下表說明所有政策父項元素的共同屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 視需要使用 |
不適用 | 必填 |
continueOnError |
如果設為「 如果設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName>元素
除 name
屬性外,一併使用
管理 UI Proxy 編輯器,使用不同的自然語言名稱。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<Allow> 元素
指定配額的計數限制。如果政策的計數器達到此限制值,後續的呼叫會遭到拒絕,直到計數器重設為止。
以下列舉三種設定 <Allow>
元素的方式:
<Allow count="2000"/>
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
如果同時指定 count
和 countRef
,則 countRef
的優先順序較高。如果 countRef
在執行階段未解析,則會使用 count
的值。
預設值: | 無 |
外觀狀態: | 選用 |
類型: | 整數 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
數量 |
用於指定配額的訊息數量。 舉例來說,如果 |
2000 | 選用 |
countRef |
用於指定含有配額訊息計數的流程變數。 |
無 | 選用 |
<Allow>/<Class> 元素
<Class>
元素可讓您根據資料流變數的值,設定 <Allow>
元素的值條件。對於 <Class>
的每個不同 <Allow>
子項標記,政策會維護不同的計數器。
如要使用 <Class>
元素,請使用 ref
屬性指定 <Class>
標記的資料流變數。接著,Edge 會使用資料流變數的值選取其中一個 <Allow>
子標記,以決定政策允許的數量。Edge 會將流程變數的值與 <Allow>
標記的 class
屬性相符,如下所示:
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
在這個範例中,目前配額計數器會根據每個要求傳遞的 time_variable
查詢參數值決定。該變數的值可以是 peak_time
或 off_peak_time
。如果查詢參數含有無效值,政策會傳回配額違規錯誤。
預設值: | 無 |
外觀狀態: | 選用 |
類型: | 無 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
ref |
用於指定包含配額配額類別的資料流變數。 |
無 | 必填 |
<Allow>/<Class>/<Allow> 元素
<Allow>
元素會指定 <Class>
元素定義的配額計數器限制。對於 <Class>
的每個不同 <Allow>
子項標記,政策都會維護不同的計數器。
例如:
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
在這個範例中,配額政策會維護兩個名為 peak_time
和 off_peak_time
的配額計數器。
預設值: | 無 |
外觀狀態: | 選用 |
類型: | 無 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
類別 |
定義配額計數器的名稱。 |
無 | 必填 |
數量 | 指定計數器的配額限制。 | 無 | 必填 |
<Interval> 元素
可用來指定整數 (例如 1、2、5、60 等等),並與您指定的 TimeUnit
(分鐘、小時、天、週或月) 搭配使用,以便決定 Edge 計算配額用量的時間範圍。
舉例來說,如果 Interval
為 24
,而 TimeUnit
為 hour
,表示系統會在 24 小時內計算配額。
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
預設值: | 無 |
外觀狀態: | 必填 |
類型: | 整數 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
ref |
用於指定包含配額間隔的資料流變數。 |
無 | 選用 |
<TimeUnit> 元素
用於指定適用於配額的時間單位。
舉例來說,如果 Interval
為 24
,而 TimeUnit
為 hour
,表示系統會在 24 小時內計算配額。
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
預設值: | 無 |
外觀狀態: | 必填 |
類型: |
字串。請從 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
ref | 用於指定包含配額時間單位的資料流變數。ref 優先於明確的間隔值。如果 ref 在執行階段未解析,則會使用該值。 |
無 | 選用 |
<StartTime> 元素
當 type
設為 calendar,
時,系統會指定配額計數器開始計數的日期和時間,無論是否已從任何應用程式收到任何要求。
例如:
<StartTime>2017-7-16 12:00:00</StartTime>
預設值: | 無 |
外觀狀態: | 當 type 設為 calendar 時,此為必要屬性。 |
類型: |
採用 ISO 8601 日期和時間格式的字串。 |
<Distributed> 元素
Edge 安裝作業可使用一或多個訊息處理器來處理要求。將這個元素設為 true
,指定政策應維護中央計數器,並持續在所有訊息處理器之間同步。訊息處理器可跨可用區和/或區域。
如果您使用 false
的預設值,則可能會超出配額,因為每個訊息處理器的計數並未共用:
<Distributed>true</Distributed>
為確保計數器同步且在每次要求中更新,請將 <Distributed>
和 <Synchronous>
設為 true:
<Distributed>true</Distributed> <Synchronous>true</Synchronous>
預設值: | false |
外觀狀態: | 選用 |
類型: | 布林值 |
<Synchronous> 元素
將其設為 true
,即可同步更新分散配額計數器。這表示在對 API 要求檢查配額時,計數器也會同時更新。如果您絕對不允許任何 API 呼叫超過配額,請將其設為 true
。
設為 false
可非同步更新配額計數器。這表示部分超出配額的 API 呼叫可能會通過,具體取決於中央存放區中的配額計數器何時異步更新。不過,您不會面臨同步更新可能造成的效能影響。
預設的非同步更新間隔為 10 秒。請使用 AsynchronousConfiguration
元素設定這項非同步行為。
<Synchronous>false</Synchronous>
預設值: | false |
外觀狀態: | 選用 |
類型: | 布林值 |
<AsynchronousConfiguration> 元素
在政策設定元素 <Synchronous>
不存在或存在且設為 false
時,設定分散式配額計數器的同步處理間隔。
您可以使用 SyncIntervalInSeconds
或 SyncMessageCount
子元素,在一段時間或訊息計數後同步處理。這兩種模式互斥。例如:
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
或
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
預設值: | SyncIntervalInSeconds = 10 秒 |
外觀狀態: | 選用;如果 <Synchronous> 設為 true ,系統會忽略這個屬性。 |
類型: |
建築 |
<AsynchronousConfiguration>/<SyncIntervalInSeconds> 元素
可用於覆寫預設行為,在 10 秒間隔後執行非同步更新。
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
如「限制」主題所述,同步處理間隔必須大於等於 10 秒。
預設值: | 10 |
外觀狀態: | 選用 |
類型: |
整數 |
<AsynchronousConfiguration>/<SyncMessageCount> element
指定配額更新期間,所有 Apigee 訊息處理器的要求數量。
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
這個範例會指定每個 Apigee Edge 訊息處理器每 5 個要求更新一次配額計數。
預設值: | 不適用 |
外觀狀態: | 選用 |
類型: |
整數 |
<Identifier> 元素
使用 <Identifier>
元素設定政策,以便根據流程變數建立不重複的計數器。
如果您不使用這個元素,政策會使用單一計數器,並套用至配額。
以下 Apigee 社群文章也討論了這個元素: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html。
<Identifier ref="verifyapikey.verify-api-key.client_id"/>
預設值: | 無 |
外觀狀態: | 選用 |
類型: |
字串 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
ref |
指定流程變數,用於識別要用於要求的計數器。此 ID 可以是 HTTP 標頭、查詢參數、表單參數或訊息內容,這些內容皆為各個應用程式、應用程式使用者、應用程式開發人員、API 產品或其他特徵專屬。 最常用來識別應用程式的 在某些情況下,必須在無法取得 |
無 | 選用 |
<MessageWeight> 元素
用於指定指派給每則訊息的權重。使用訊息權重可提高要求訊息的影響力,例如比其他訊息耗用更多運算資源。
舉例來說,您想將 POST 訊息計為「重」或「昂貴」的兩倍,而非 GET 訊息。因此,您將 MessageWeight
設為 2 (代表 POST) 和 1 (代表 GET)。您甚至可以將 MessageWeight
設為 0,讓要求不會影響計數器。在這個範例中,如果配額為每分鐘 10 則訊息,且 POST 要求的 MessageWeight
為 2
,則配額會允許在任何 10 分鐘間隔內提出 5 個 POST 要求。在計數器重設之前,任何額外要求 (POST 或 GET) 都會遭到拒絕。
代表 MessageWeight
的值必須由流程變數指定,且可從 HTTP 標頭、查詢參數、XML 或 JSON 要求酬載,或任何其他流程變數中擷取。舉例來說,您可以在名為 weight
的標頭中設定:
<MessageWeight ref="message_weight"/>
預設值: | 無 |
外觀狀態: | 選用 |
類型: |
整數 |
流程變數
執行配額政策時,系統會自動填入下列預先定義的流程變數。如要進一步瞭解 Flow 變數,請參閱「變數參考資料」。
變數 | 類型 | 權限 | 說明 |
---|---|---|---|
ratelimit.{policy_name}.allowed.count | 長 | 唯讀 | 傳回允許的配額數量 |
ratelimit.{policy_name}.used.count | 長 | 唯讀 | 傳回在配額間隔內目前使用的配額 |
ratelimit.{policy_name}.available.count | 長 | 唯讀 | 傳回配額間隔內的可用配額數量 |
ratelimit.{policy_name}.exceed.count | 長 | 唯讀 | 超過配額後會傳回 1。 |
ratelimit.{policy_name}.total.exceed.count | 長 | 唯讀 | 超過配額後會傳回 1。 |
ratelimit.{policy_name}.expiry.time | 長 | 唯讀 |
以毫秒為單位,傳回世界標準時間,用於決定配額到期時間和新配額間隔開始時間。 當配額政策類型為 |
ratelimit.{policy_name}.identifier | 字串 | 唯讀 | 傳回附加至政策的 (用戶端) ID 參照 |
ratelimit.{policy_name}.class | 字串 | 唯讀 | 傳回與用戶端 ID 相關聯的類別 |
ratelimit.{policy_name}.class.allowed.count | 長 | 唯讀 | 傳回類別中定義的配額數量上限 |
ratelimit.{policy_name}.class.used.count | 長 | 唯讀 | 傳回類別中已使用的配額 |
ratelimit.{policy_name}.class.available.count | 長 | 唯讀 | 傳回類別中可用的配額數量 |
ratelimit.{policy_name}.class.exceed.count | 長 | 唯讀 | 傳回目前配額間隔中,超出類別限制要求的數量 |
ratelimit.{policy_name}.class.total.exceed.count | 長 | 唯讀 | 傳回在所有配額間隔中,超過類別上限要求的總數,也就是所有配額間隔的 class.exceed.count 總和。 |
ratelimit.{policy_name}.failed | 布林值 | 唯讀 |
表示政策是否失敗 (true 或 false)。 |
錯誤參考資料
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 | Occurs if the <Interval> element is not defined within the Quota policy. This element
is mandatory and used to specify the interval of time applicable to the quota. The time interval
can be minutes, hours, days, weeks, or months as defined with the <TimeUnit> element. |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | Occurs if the <TimeUnit> element is not defined within the Quota policy. This element
is mandatory and used to specify the unit of time applicable to the quota. The time interval
can be in minutes, hours, days, weeks, or months. |
build |
policies.ratelimit.InvalidMessageWeight |
500 | Occurs if the value of the <MessageWeight> element specified through a flow variable
is invalid (a non-integer value). |
build |
policies.ratelimit.QuotaViolation |
500 | The quota limit was exceeded. | N/A |
Deployment errors
Error name | Cause | Fix |
---|---|---|
InvalidQuotaInterval |
If the quota interval specified in the <Interval> element is not
an integer, then the deployment of the API proxy fails. For example, if the quota interval
specified is 0.1 in the <Interval> element, then the deployment of the
API proxy fails.
|
build |
InvalidQuotaTimeUnit |
If the time unit specified in the <TimeUnit> element is unsupported,
then the deployment of the API proxy fails. The supported time units are minute ,
hour , day , week , and month .
|
build |
InvalidQuotaType |
If the type of the quota specified by the type attribute in the <Quota>
element is invalid, then the deployment of the API proxy fails. The
supported quota types are default , calendar , flexi , and rollingwindow .
|
build |
InvalidStartTime |
If the format of the time specified in the <StartTime> element is
invalid, then the deployment of the API proxy fails. The valid format is yyyy-MM-dd HH:mm:ss ,
which is the ISO 8601 date and time format. For
example, if the time specified in the <StartTime> element is
7-16-2017 12:00:00 then the deployment of the API proxy fails.
|
build |
StartTimeNotSupported |
If the <StartTime> element is specified whose quota type is not
calendar type, then the deployment of the API proxy fails. The <StartTime> element is
supported only for the calendar quota type. For example, if the type attribute is set
to flexi or rolling window in the <Quota> element, then the
deployment of the API proxy fails.
|
build |
InvalidTimeUnitForDistributedQuota |
If the <Distributed> element is set to true and the <TimeUnit> element is set to
second then the deployment of the API proxy fails. The timeunit second is invalid for
a distributed quota. |
build |
InvalidSynchronizeIntervalForAsyncConfiguration |
If the value specified for the <SyncIntervalInSeconds> element within the
<AsynchronousConfiguration> element in a Quota policy is less than zero, then the
deployment of the API proxy fails. |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
If the value of the <AsynchronousConfiguration> element is set to true in a Quota policy, which also
has asynchronous configuration defined using the <AsynchronousConfiguration> element, then
the deployment of the API proxy fails. |
build |
Fault variables
These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "QuotaViolation" |
ratelimit.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | ratelimit.QT-QuotaPolicy.failed = true |
Example error response
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.QuotaViolation" }, "faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : _default" } }
Example fault rule
<FaultRules> <FaultRule name="Quota Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "QuotaViolation") </Condition> </Step> <Condition>ratelimit.Quota-1.failed=true</Condition> </FaultRule> </FaultRules>