配額政策

您正在查看 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 標頭值。該變數的值可以是 platinumsilver。如果標頭含有無效值,政策會傳回配額違規錯誤。


關於配額政策

配額是 API Proxy 可在一段時間內 (例如分鐘、小時、日、週或月) 處理的要求訊息配額。政策會維護計數器,用於計算 API Proxy 收到的要求數量。這項功能可讓 API 供應器在一段時間內,強制限制應用程式發出的 API 呼叫次數。例如,您可以使用配額政策限制應用程式每分鐘提出 1 次要求,或每月提出 10,000 次要求。

舉例來說,如果配額定義為每月 10,000 則郵件,則會在第 10,000 則郵件後開始實施速率限制。無論是第一天還是該週期的最後一天,只要有 10,000 則訊息,系統就會自動重設配額計數器,直到指定時間間隔結束為止。如果您想在指定時間間隔結束前,就允許額外要求,則必須使用重設配額政策明確重設配額。

配額的變化版本「SpikeArrest」可防止因用量突然增加、用戶端發生錯誤或遭受惡意攻擊而導致的流量尖峰 (或爆量)。如要進一步瞭解 SpikeArrest,請參閱「尖峰流量防範政策」。

配額適用於個別 API Proxy,不會在 API Proxy 之間分配。舉例來說,如果 API 產品中有三個 API Proxy,即使三者都使用相同的配額政策設定,也不會共用單一配額。

配額政策類型

配額政策支援多種不同類型的政策:預設、calendarflexirollingwindow。每個類型都會定義配額計數器的啟動和重設時間,如下表所示:

時間單位 預設 (或空值) 重設 日曆重設 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:0024:00:00 這兩種符號可用於區分可與某一日期相關聯的兩個午夜。因此,2015-02-04 24:00:002015-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">

下列屬性僅適用於這項政策。

屬性 說明 預設 存在必要性
類型

用於決定配額計數器檢查配額用量的時間和方式。詳情請參閱「配額政策類型」。

如果省略 type 值,計數器會從分鐘/小時/天/週/月開始計算。

有效值包括:

  • calendar:根據明確的開始時間設定配額。每個應用程式的配額計數器會根據您設定的 <StartTime><Interval><TimeUnit> 值進行重新整理。
  • rollingwindow:設定使用「滾動視窗」的配額,以便判斷配額使用情形。使用 rollingwindow 時,您可以透過 <Interval><TimeUnit> 元素決定視窗的大小,例如 1 天。當要求傳入時,Edge 會查看要求的確切時間 (例如下午 5 點 1 分),計算在該時間與前一天下午 5 點 1 分之間傳入的要求數量 (1 天),並判斷是否在該時間範圍內超出配額。
  • flexi:設定配額,讓計數器在從應用程式收到第一個要求訊息時開始運作,並根據 <Interval>, <TimeUnit> 值重設。
日曆 選用

下表說明所有政策父項元素的共同屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素,為政策加上標籤: 管理使用者介面 Proxy 編輯器,使用不同的自然語言名稱。

不適用 必填
continueOnError

如果設為「false」,系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true,即使政策已發生,流程執行作業仍會繼續執行 失敗。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

&lt;DisplayName&gt;元素

name 屬性外,一併使用 管理 UI Proxy 編輯器,使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,政策的 name 屬性值會是

存在必要性 選用
類型 字串

<Allow> 元素

指定配額的計數限制。如果政策的計數器達到此限制值,後續的呼叫會遭到拒絕,直到計數器重設為止。

以下列舉三種設定 <Allow> 元素的方式:

<Allow count="2000"/> 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

如果同時指定 countcountRef,則 countRef 的優先順序較高。如果 countRef 在執行階段未解析,則會使用 count 的值。

預設值:
外觀狀態: 選用
類型: 整數

屬性

屬性 說明 預設 存在必要性
數量

用於指定配額的訊息數量。

舉例來說,如果 count 屬性值為 100、Interval 為 1,TimeUnit 為月,就會指定每月 100 則訊息的配額。

2000 選用
countRef

用於指定含有配額訊息計數的流程變數。countRef 優先於 count 屬性。

選用

<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_timeoff_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_timeoff_peak_time 的配額計數器。

預設值:
外觀狀態: 選用
類型:

屬性

屬性 說明 預設 存在必要性
類別

定義配額計數器的名稱。

必填
數量 指定計數器的配額限制。 必填

<Interval> 元素

可用來指定整數 (例如 1、2、5、60 等等),並與您指定的 TimeUnit (分鐘、小時、天、週或月) 搭配使用,以便決定 Edge 計算配額用量的時間範圍。

舉例來說,如果 Interval24,而 TimeUnithour,表示系統會在 24 小時內計算配額。

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
預設值:
外觀狀態: 必填
類型: 整數

屬性

屬性 說明 預設 存在必要性
ref

用於指定包含配額間隔的資料流變數。ref 優先於明確的間隔值。如果同時指定參照和值,則參照的優先順序較高。如果 ref 在執行階段未解析,則會使用該值。

選用

<TimeUnit> 元素

用於指定適用於配額的時間單位。

舉例來說,如果 Interval24,而 TimeUnithour,表示系統會在 24 小時內計算配額。

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
預設值:
外觀狀態: 必填
類型:

字串。請從 minutehourdayweekmonth 中選取。

屬性

屬性 說明 預設 存在必要性
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 時,設定分散式配額計數器的同步處理間隔。

您可以使用 SyncIntervalInSecondsSyncMessageCount 子元素,在一段時間或訊息計數後同步處理。這兩種模式互斥。例如:

<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> 元素設定政策,以便根據流程變數建立不重複的計數器。

您可以為流程變數定義的特性建立不重複的計數器。舉例來說,您可以使用開發人員電子郵件地址,將配額與特定開發人員連結。無論您使用的是自訂變數或預先定義變數 (例如 驗證 API 金鑰政策中提供的變數),都可以使用各種變數來識別配額。另請參閱變數參考資料

如果您不使用這個元素,政策會使用單一計數器,並套用至配額。

以下 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 產品或其他特徵專屬。

最常用來識別應用程式的 <Identifier>client_idclient_id 是 API 金鑰或消費者金鑰的另一個名稱,當應用程式在 Apigee Edge 的機構中註冊時,系統會為該應用程式產生這類金鑰。如果您已為 API 啟用 API 金鑰或 OAuth 授權政策,就可以使用這個 ID。

在某些情況下,必須在無法取得 client_id 的情況下擷取配額設定,例如在沒有安全性政策的情況下。在這種情況下,您可以使用「存取實體」政策來擷取適當的 API 產品設定,然後使用「ExtractVariables」擷取值,並在「配額」政策中使用擷取的內容變數。詳情請參閱「存取實體政策」。

選用

<MessageWeight> 元素

用於指定指派給每則訊息的權重。使用訊息權重可提高要求訊息的影響力,例如比其他訊息耗用更多運算資源。

舉例來說,您想將 POST 訊息計為「重」或「昂貴」的兩倍,而非 GET 訊息。因此,您將 MessageWeight 設為 2 (代表 POST) 和 1 (代表 GET)。您甚至可以將 MessageWeight 設為 0,讓要求不會影響計數器。在這個範例中,如果配額為每分鐘 10 則訊息,且 POST 要求的 MessageWeight2,則配額會允許在任何 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 唯讀

以毫秒為單位,傳回世界標準時間,用於決定配額到期時間和新配額間隔開始時間。

當配額政策類型為 rollingwindow 時,這個值無效,因為配額間隔不會到期。

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.
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.
policies.ratelimit.InvalidMessageWeight 500 Occurs if the value of the <MessageWeight> element specified through a flow variable is invalid (a non-integer value).
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.
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.
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.
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.
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.
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.
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.
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.

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>

結構定義

相關主題

ResetQuota 政策

SpikeArrest 政策

比較配額、尖峰流量截斷和並發速率限制政策