配額政策

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

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

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

部署錯誤

錯誤變數

當這項政策觸發錯誤時，系統會設定這些變數。詳情請參閱重要須知 政策錯誤。

錯誤回應範例

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

結構定義

相關主題

ResetQuota 政策

SpikeArrest 政策

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