配額政策

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

結果

您可以使用配額政策，設定 API Proxy 在一段時間內 (例如 1 分鐘、1 小時、1 天、1 週或 1 個月) 允許的要求訊息數量。您可以為所有存取 API 代理程式的應用程式設定相同的配額，也可以根據下列項目設定配額：

• 包含 API Proxy 的產品
• 要求 API 的應用程式
• 應用程式開發人員
• 許多其他條件

請勿使用配額來防範整體流量激增情形。請使用 SpikeArrest 政策。請參閱「尖峰流量防範政策」。

影片

以下影片介紹配額政策的配額管理功能：

範例

以下政策程式碼範例說明如何透過以下方式開始和結束配額期間：

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

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

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

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

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

<Identifier ref="request.queryparam.id"/>

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

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

關於配額政策

配額是 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。每個類型都會定義配額計數器的啟動和重設時間，如下表所示：

對於 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">

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

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

&lt;DisplayName&gt;元素

除 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 的值。

屬性

<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。如果查詢參數含有無效值，政策會傳回配額違規錯誤。

屬性

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

屬性

<StartTime> 元素

當 type 設為 calendar, 時，系統會指定配額計數器開始計數的日期和時間，無論是否已從任何應用程式收到任何要求。

例如：

<StartTime>2017-7-16 12:00:00</StartTime>

<Distributed> 元素

Edge 安裝作業可使用一或多個訊息處理器來處理要求。將這個元素設為 true，指定政策應維護中央計數器，並持續在所有訊息處理器之間同步。訊息處理器可跨可用區和/或區域。

如果您使用 false 的預設值，則可能會超出配額，因為每個訊息處理器的計數並未共用：

<Distributed>true</Distributed>

為確保計數器同步且在每次要求中更新，請將 <Distributed> 和 <Synchronous> 設為 true：

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous> 元素

將其設為 true，即可同步更新分散配額計數器。這表示在對 API 要求檢查配額時，計數器也會同時更新。如果您絕對不允許任何 API 呼叫超過配額，請將其設為 true。

設為 false 可非同步更新配額計數器。這表示部分超出配額的 API 呼叫可能會通過，具體取決於中央存放區中的配額計數器何時異步更新。不過，您不會面臨同步更新可能造成的效能影響。

預設的非同步更新間隔為 10 秒。請使用 AsynchronousConfiguration 元素設定這項非同步行為。

<Synchronous>false</Synchronous>

<AsynchronousConfiguration> 元素

在政策設定元素 <Synchronous> 不存在或存在且設為 false 時，設定分散式配額計數器的同步處理間隔。

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

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

或

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

<AsynchronousConfiguration>/<SyncIntervalInSeconds> 元素

可用於覆寫預設行為，在 10 秒間隔後執行非同步更新。

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

如「限制」主題所述，同步處理間隔必須大於等於 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"/>

屬性

<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 變數，請參閱「變數參考資料」。

錯誤參考資料

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.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

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 政策

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