配額政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

使用配額政策來設定 API Proxy 允許的要求訊息數量 一段時間，例如分鐘、小時、日、週或月。您可以將配額設為 同樣適用於存取 API Proxy 的所有應用程式，您也可以根據下列項目設定配額：

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

請勿使用配額來防範整體流量遽增的情況。在這方面，請走到「尖銳妙招」 政策。請參閱 Spike Arrest 政策。

影片

以下影片說明如何透過配額政策管理配額：

範例

這些政策程式碼範例說明如何透過以下方式設定配額週期：

<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，請參閱《Spike Arrest 政策》。

配額適用於個別 API Proxy，且不會分配到 API Proxy 中。例如： 如果在一項 API 產品中有三個 API Proxy，則一個配額不會供這三個 API 共用 就算這三項都使用相同的配額政策設定也一樣。

配額政策類型

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

如果是 type="calendar"，您必須指定 <StartTime>。

資料表不會列出 rollingwindow 類型的值。滾動週期 配額是設定配額「時間範圍」的大小，例如 1 小時或一天的時間範圍。如果 政策會判斷配額在過去是否已超過配額 「視窗」讓應用程式從可以最快做出回應的位置 回應使用者要求

例如，您定義一個小時內允許 1000 個要求的時段。新要求 這項規則會計算過去 2 小時內的配額數量 也就是從下午 2:45 算起的要求數量如果該配額 2 小時，則系統會允許該要求。

一分鐘後，下午 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 反面模式。

或者，您也可以在 API Proxy 中定義多項配額政策， 政策。每個配額政策都有自己的計數器， 政策的 name 屬性。

或者，使用 以下位置中的 <Class> 或 <Identifier> 元素： 配額政策，可在單一政策中定義多個不重複的計數器。只要使用這些節點 元素，單一政策可根據發出要求的應用程式維護不同的計數器； 發出請求的應用程式開發人員、用戶端 ID 或其他用戶端 ID 等。詳情請參閱 請參閱上述範例，進一步瞭解如何使用 <Class> 或 <Identifier> 元素。

時間標記法

所有配額時間均設為座標通用 時間 (世界標準時間)。

配額時間標記法採用國際標準日期標記法 標準 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.VerifyAPIKey.apiproduct.* 變數： 名為「VerifyAPIKey」的 Verification API 金鑰政策用於檢查要求中的應用程式 API 金鑰。 變數值來自與金鑰相關聯的 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> 元素的分割要求。適用對象 每個不同的 <Allow> 子標記 <Class> 政策會維護不同的計數器

如要使用 <Class> 元素，請使用 將 ref 屬性設為 <Class> 標記。接著，邊緣會使用 流程變數，選取其中一個 <Allow> 子標記，以決定允許 政策的數量。邊緣比對 Flow 變數的值和 class <Allow> 標記的屬性，如下所示：

<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> 元素定義。對於每項 不同的 <Allow> 子標記 (<Class> 的子標記)、 政策維護了不同的計數器。

例如：

<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 (分鐘、小時、天、週或月) 來決定時間 這段期間內，Edge 會計算配額用量。

例如 24 的 Interval，且 hour 的 TimeUnit 表示配額將 計算依據為 24 小時的期間

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

屬性

<TimeUnit>元素

用於指定配額適用的時間單位。

例如 24 的 Interval，且 hour 的 TimeUnit 表示配額將 計算依據為 24 小時的期間

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

屬性

<StartTime>元素

將 type 設為 calendar, 時，系統會指定日期 配額計數器開始計算的時間，以及無論要求是否送出要求 接收的影格速率

當 type 已明確設定時，您必須提供明確的 StartTime 將 指向 calendar, ，您就無法使用資料流變數的參照。如果您指定 在沒有設定 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>

&lt;Synchronous&gt;元素

如要同步更新分散式配額計數器，請設為 true。這個 這表示系統會同時檢查計數器的更新，並同時檢查要求配額 至 API如果您必須不允許任何 API，請設為 true 配額。

如要以非同步方式更新配額，請設為 false。也就是說 部分 API 呼叫可能會超過配額，實際情況取決於 中央存放區中的配額計數器會非同步更新。不過您不一定會面對 同步更新潛在的效能影響。

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

<Synchronous>false</Synchronous>

&lt;AsynchronousConfiguration&gt;元素

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

您可以使用 SyncIntervalInSeconds 或 SyncMessageCount 子元素。 而且互斥。例如：

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

或

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

&lt;AsynchronousConfiguration&gt;/&lt;SyncIntervalInSeconds&gt; 元素

這可以覆寫預設行為，也就是在出現非同步更新後 間隔為 10 秒

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

同步間隔必須 >= 10 秒，如 限制主題。

&lt;AsynchronousConfiguration&gt;/&lt;SyncMessageCount&gt;元素

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

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

這個範例會指定每個 Apigee 中的配額，每 5 個要求會更新一次 邊緣訊息處理器。

&lt;Identifier&gt;元素

使用 <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"/>

屬性

&lt;MessageWeight&gt;元素

用於指定指派給每則訊息的權重。使用訊息權重來增加 要求訊息，例如消耗更多運算資源。

舉例來說，您想要將 POST 訊息計為「重型」的兩倍或價格較高 訊息。因此，您需要將 POST 的 MessageWeight 設為 2，並將 。您甚至可以將 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 政策

比較 配額、尖峰攻擊和並行頻率限制政策