您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
使用配額政策來設定 API Proxy 在一段時間內 (例如一分鐘、每小時、每天、每週或一個月) 允許的要求訊息數量。您可以將配額設為所有存取 API Proxy 的應用程式,或是依據以下項目設定配額:
- 包含 API Proxy 的產品
- 要求 API 的應用程式
- 應用程式開發人員
- 其他許多條件
請勿使用配額來因應整體流量高峰。為此,請使用「高點逮捕」政策。請參閱滑板騎士政策。
影片
下列影片介紹配額政策的配額管理機制:
簡介 (新邊緣)
簡介 (經典邊緣)
動態配額
分散式與同步
訊息權重
日曆
滾動週期
彈性
條件式配額
流程變數
處理錯誤
範例
這些政策程式碼範例說明如何透過以下方式開始及結束配額期:
更多動態配額
<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 Proxy。詳情請參閱「建立 API 產品」一文。
在上述範例中,含有配額政策的 API Proxy 使用名為 verify-api-key
的 VerifyAPIKey 政策,以驗證要求中傳遞的 API 金鑰。接著,配額政策會存取 VerifyAPIKey 政策中的流程變數,讀取 API 產品上設定的配額值。如要進一步瞭解 VerifyAPIKey 流程變數,請參閱「驗證 API 金鑰政策」。
另一種做法是為個別開發人員或應用程式設定自訂屬性,然後在配額政策中讀取這些值。例如,您希望為每位開發人員設定不同的配額值。在這種情況下,您可以在開發人員中設定自訂屬性,其中包含限制、時間單位和間隔。接著,您可以在配額政策中參照這些值,如下所示:
<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>
值。時間值為 GMT 時間,而非當地時間。如未針對 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 Proxy 中使用這些流程變數來執行條件式處理作業、在即將達到配額限制時監控政策、將目前的配額計數器傳回應用程式,或其他原因。
由於政策的流程變數是以 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,則計數器每十二小時會重設一次。
你可以將 <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,即使這三個 Proxy 使用相同的配額政策設定,系統也不會共用同一項配額。
配額政策類型
配額政策支援多種不同類型的政策:預設、calendar
、flexi
和 rollingwindow
。每種類型都會定義配額計數器的開始與重設時間,如下表所示:
時間單位 | 預設 (或空值) 重設 | 重設日曆 | Flex 重設 |
---|---|---|---|
分鐘 | 接下來一分鐘的開始時間 | <StartTime> 過後 1 分鐘 |
首次提出要求後一分鐘 |
小時 | 接下來一小時內 | <StartTime> 過後 1 小時 |
首次提出要求後的一小時內 |
天 | 午夜 (格林威治標準時間) | <StartTime> 過後 24 小時 |
首次提出要求後 24 小時 |
週 | 午夜 (格林威治標準時間) 週日午夜 | <StartTime> 過後一週 |
首次提出要求後的一週 |
個月 | 當月最後一天的午夜 (GMT) | <StartTime> 起一個月 (28 天) |
首次申請後一個月 (28 天) |
對於 type="calendar"
,您必須指定 <StartTime>
的值。
資料表不會列出 rollingwindow
類型的值。滾動週期配額的運作方式是設定配額「效期」的大小,例如一個小時或一天。收到新要求時,政策會判斷配額是否在過去「週期」內已超出配額。
例如,您可以定義一個兩個小時的時間範圍,允許傳送 1, 000 個要求。新的要求發生時間為下午 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
代表午夜前一秒的時間。
請注意,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>
標記指定流程變數。接著,邊緣會使用流程變數的值選取其中一個 <Allow>
子標記,決定允許的政策數量。邊緣會將流程變數的值與 <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
。如果查詢參數包含無效的值,政策會傳回配額違規錯誤。
預設: | 不適用 |
所在地: | 選用 |
類型: | 不適用 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
參考資料 |
用於指定包含配額配額類別的流程變數。 |
無 | 必要 |
<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>
預設: | 無 |
所在地: | 必要 |
類型: | 整數 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
參考資料 |
用來指定含有配額間隔的流程變數。 |
無 | 選用 |
<TimeUnit> 元素
用於指定配額適用的時間單位。
舉例來說,如果 Interval
為 24
且 TimeUnit
為 hour
,代表系統會在 24 小時內計算配額。
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
預設: | 無 |
所在地: | 必要 |
類型: |
字串。請選取 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
參考資料 | 用於指定含有配額時間單位的流程變數。ref 的優先順序高於明確間隔值。如果 ref 未在執行階段解析,系統會使用這個值。 |
無 | 選用 |
<StartTime> 元素
將 type
設為 calendar,
時,不論是否收到任何應用程式的任何要求,配額計數器都會開始計算的日期和時間。
當 type
明確設為 calendar,
時,您必須提供明確的 StartTime
不能使用資料流變數的參照;如果在未設定 type
值時指定 StartTime
值,則會收到錯誤訊息。
例如:
<StartTime>2017-7-16 12:00:00</StartTime>
預設: | 無 |
所在地: | 當 type 設為 calendar 時需要。 |
類型: |
採用 ISO 8601 日期和時間格式的字串。 |
<分散式> 元素
安裝 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 |
所在地: | 選用 |
類型: | 布林值 |
<AsyncConfiguration> 元素
當政策設定元素 <Synchronous>
不存在或存在且設為 false
時,設定分散式配額計數器之間的同步處理間隔。
您可以使用 SyncIntervalInSeconds
或 SyncMessageCount
子項元素,在時間範圍或訊息數之後同步處理。兩者無法並用。比如
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
或
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
預設: | SyncIntervalInSeconds = 10 秒 |
所在地: | 選用;當 <Synchronous> 設為 true 時會忽略。 |
類型: |
建築 |
<AsyncConfiguration>/<SyncIntervalInSeconds> 元素
這可覆寫在 10 秒間隔後,執行非同步更新的預設行為。
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
同步處理間隔必須大於或等於 10 秒,如限制主題中所述。
預設: | 10 |
所在地: | 選用 |
類型: |
整數 |
<AsyncConfiguration>/<SyncMessageCount> 元素
指定配額更新之間的所有 Apigee 訊息處理器要求數量。
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
這個範例指定每個 Apigee Edge 訊息處理器的配額數量,每 5 個要求會更新一次。
預設: | n/a |
所在地: | 選用 |
類型: |
整數 |
<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"/>
預設: | 不適用 |
所在地: | 選用 |
類型: |
字串 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
參考資料 |
指定流程變數,用來識別用於要求的計數器。ID 可以是 HTTP 標頭、查詢參數、表單參數或個別應用程式、應用程式使用者、應用程式開發人員、API 產品或其他特性的訊息內容。 最常用於識別應用程式的 在某些情況下,如果沒有 |
不適用 | 選用 |
<MessageWeight> 元素
用來指定指派給每則訊息的權重。使用訊息權重提高要求訊息的影響,例如耗用的運算資源比其他資源更多。
舉例來說,您可以將 POST 訊息計為「大量」或「高價」的 GET 訊息。因此,您將 POST 的 MessageWeight
設為 2,GET 則設為 1。您甚至可以將 MessageWeight
設為 0,讓要求不會影響計數器。在此範例中,如果每分鐘 10 則訊息的配額,而 POST 要求的 MessageWeight
為 2
,則配額會允許每 10 分鐘間隔 5 則 POST 要求。在計數器重設之前,任何額外要求 (POST 或 GET) 都會遭到拒絕。
代表 MessageWeight
的值必須由流程變數指定,且可從 HTTP 標頭、查詢參數、XML 或 JSON 要求酬載或任何其他流程變數中擷取。舉例來說,您可以在名為 weight
的標頭中設定:
<MessageWeight ref="message_weight"/>
預設: | 不適用 |
所在地: | 選用 |
類型: |
整數 |
流程變數
執行配額政策時,系統會自動填入下列預先定義的流程變數。如要進一步瞭解流程變數,請參閱變數參考資料。
變數 | 類型 | 權限 | 說明 |
---|---|---|---|
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)。 |
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 | 如未在配額政策中定義 <Interval> 元素,就會發生這個問題。此為必要元素,用來指定配額適用的時間間隔。時間間隔可以是以 <TimeUnit> 元素定義的分鐘、小時、天、週或月。 |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | 如未在配額政策中定義 <TimeUnit> 元素,就會發生這個問題。此為必要元素,用於指定配額適用的時間單位。時間間隔可以是分鐘、小時、天、週或月。 |
build |
policies.ratelimit.InvalidMessageWeight |
500 | 如果透過流程變數指定的 <MessageWeight> 元素值無效 (非整數值),就會發生這個問題。 |
build |
policies.ratelimit.QuotaViolation |
500 | 超過配額限制。 | 不適用 |
部署錯誤
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidQuotaInterval |
如果 <Interval> 元素中指定的配額間隔不是整數,API Proxy 的部署就會失敗。舉例來說,如果在 <Interval> 元素中指定的配額間隔為 0.1,API Proxy 的部署就會失敗。 |
build |
InvalidQuotaTimeUnit |
如果不支援 <TimeUnit> 元素中指定的時間單位,API Proxy 的部署就會失敗。支援的時間單位為 minute 、hour 、day 、week 和 month 。 |
build |
InvalidQuotaType |
如果 <Quota> 元素中 type 屬性指定的配額類型無效,API Proxy 的部署就會失敗。支援的配額類型為 default 、calendar 、flexi 和 rollingwindow 。 |
build |
InvalidStartTime |
如果 <StartTime> 元素中指定的時間格式無效,API Proxy 的部署就會失敗。有效的格式為 yyyy-MM-dd HH:mm:ss ,採 ISO 8601 日期和時間格式。舉例來說,如果 <StartTime> 元素中指定的時間是 7-16-2017 12:00:00 ,API Proxy 的部署就會失敗。 |
build |
StartTimeNotSupported |
如果指定 <StartTime> 元素的配額類型不是 calendar 類型,API Proxy 的部署就會失敗。<StartTime> 元素僅適用於 calendar 配額類型。舉例來說,如果 <Quota> 元素中的 type 屬性設為 flexi 或 rolling window ,API Proxy 的部署就會失敗。 |
build |
InvalidTimeUnitForDistributedQuota |
如果 <Distributed> 元素設為 true ,且 <TimeUnit> 元素設為 second ,API Proxy 的部署就會失敗。分散式配額無法設定「second 」時間單位。 |
build |
InvalidSynchronizeIntervalForAsyncConfiguration |
如果在配額政策的 <AsynchronousConfiguration> 元素中針對 <SyncIntervalInSeconds> 元素指定的值小於零,API Proxy 部署就會失敗。 |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
如果配額政策中的 <AsynchronousConfiguration> 元素值設為 true ,且使用 <AsynchronousConfiguration> 元素定義非同步設定,則 API Proxy 部署作業會失敗。 |
build |
錯誤變數
系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.QuotaViolation" }, "faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : _default" } }
故障規則示例
<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>