配額政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

優勢

使用配額政策來設定 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 的變化版本可以防止因用量突然增加、發生錯誤的用戶端或惡意攻擊而導致流量遽增 (或爆發)。如要進一步瞭解 SpikeArrest，請參閱高強度跳傘政策。

配額適用於個別 API Proxy，且不會分配給 API Proxy。舉例來說，如果您在某個 API 產品中有三個 API Proxy，即使這三個 Proxy 使用相同的配額政策設定，系統也不會共用同一項配額。

配額政策類型

配額政策支援多種不同類型的政策：預設、calendar、flexi 和 rollingwindow。每種類型都會定義配額計數器的開始與重設時間，如下表所示：

對於 type="calendar"，您必須指定 <StartTime> 的值。

資料表不會列出 rollingwindow 類型的值。滾動週期配額的運作方式是設定配額「效期」的大小，例如一個小時或一天。收到新要求時，政策會判斷配額是否在過去「週期」內已超出配額。

例如，您可以定義一個兩個小時的時間範圍，允許傳送 1, 000 個要求。新的要求發生時間為下午 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 代表午夜前一秒的時間。

請注意，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">

下列屬性專屬於這項政策，

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

<DisplayName> 元素

除了 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> 標記指定流程變數。接著，邊緣會使用流程變數的值選取其中一個 <Allow> 子標記，決定允許的政策數量。邊緣會將流程變數的值與 <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, 時，不論是否收到任何應用程式的任何要求，配額計數器都會開始計算的日期和時間。

當 type 明確設為 calendar, 時，您必須提供明確的 StartTime 不能使用資料流變數的參照；如果在未設定 type 值時指定 StartTime 值，則會收到錯誤訊息。

例如：

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

<分散式> 元素

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

<AsyncConfiguration> 元素

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

您可以使用 SyncIntervalInSeconds 或 SyncMessageCount 子項元素，在時間範圍或訊息數之後同步處理。兩者無法並用。比如

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

或

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

<AsyncConfiguration>/<SyncIntervalInSeconds> 元素

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

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

同步處理間隔必須大於或等於 10 秒，如限制主題中所述。

<AsyncConfiguration>/<SyncMessageCount> 元素

指定配額更新之間的所有 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 訊息。因此，您將 POST 的 MessageWeight 設為 2，GET 則設為 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 政策

比較配額、尖峰流量防範和並行頻率限制政策