配額政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

使用配額政策設定 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>

<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 是配額的變體，可防止流量尖峰 (或爆量)，這類情況可能是因使用量突然增加、用戶端有錯誤或惡意攻擊所致。如要進一步瞭解尖峰流量防範政策，請參閱這篇文章。

配額適用於個別 API Proxy，不會在 API Proxy 之間分配。舉例來說，如果 API 產品中有三個 API Proxy，即使這三個 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 流程的多個位置使用相同的配額政策，可能會導致配額用盡的速度超出預期，這是《The Book of Apigee Edge Antipatterns》一書中描述的反模式。

或者，您可以在 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">

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

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

&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> 元素，請使用 <Class> 標記的 ref 屬性指定流程變數。然後，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> 元素

指定與您指定的 TimeUnit 配對的整數 (例如 1、2、5、60 等)，以決定 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> 元素

指定配額更新之間，所有 Apigee 訊息處理器的要求數量。

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

這個範例指定每 5 個要求更新一次配額計數，適用於每個 Apigee Edge 訊息處理器。

<Identifier> 元素

使用 <Identifier> 元素設定政策，根據流程變數建立不重複的計數器。

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

如要進一步瞭解這個元素，請參閱 Apigee 社群貼文： 不同政策的配額 ID。

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

屬性

<MessageWeight> 元素

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

舉例來說，您希望 POST 訊息的「負擔」或費用是 GET 訊息的兩倍。因此，您會將 POST 的 MessageWeight 設為 2，GET 的 MessageWeight 設為 1。您甚至可以將 MessageWeight 設為 0，這樣要求就不會影響計數器。在這個範例中，如果配額為每分鐘 10 則訊息，且 POST 要求的 MessageWeight 為 2，則配額允許在任何 10 分鐘間隔內提出 5 項 POST 要求。計數器重設前，系統會拒絕任何額外的 POST 或 GET 要求。

代表 MessageWeight 的值必須由流程變數指定，且可從 HTTP 標頭、查詢參數、XML 或 JSON 要求酬載，或任何其他流程變數中擷取。舉例來說，您可以在名為 weight 的標頭中設定：

<MessageWeight ref="message_weight"/>

流程變數

配額政策執行時，系統會自動填入下列預先定義的流程變數。如要進一步瞭解流程變數，請參閱「變數參考資料」。

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 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 政策

比較配額、Spike Arrest 和並行速率限制政策