配額政策

您目前查看的是 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"/>

流程變數

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

錯誤參考資料

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

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