配額政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

配額是指 API Proxy 在一段時間內 (例如每分鐘、每小時、每天、每週或每月) 接受的要求數。配額政策會維護計數器，計算 API Proxy 收到的要求數。API 供應商可透過這項功能，在一段時間內對應用程式發出的 API 呼叫次數強制設限。舉例來說，您可以使用配額政策，將應用程式限制為每分鐘 1 個要求，或每月 10,000 個要求。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

當 API Proxy 達到配額上限時，Apigee 會拒絕後續的 API 呼叫並傳回錯誤訊息，直到配額計數器在指定時間間隔結束時自動重設，或使用 ResetQuota 政策明確重設配額為止。

舉例來說，如果配額定義為每月 10,000 則訊息，則在第 10,000 則訊息之後，就會開始進行速率限制。無論是在當月的第一天或最後一天達到 10,000 則訊息，都算在該月內。

使用 Apigee 時，每個 API 呼叫都可以動態加權。舉例來說，使用大型語言模型 (LLM) API 時，您可以根據要求或回應中的權杖數量 (或兩者) 實施頻率限制。此外，配額限制本身可以是動態的，也就是說，您可以在系統較忙碌時強制執行更嚴格的配額，或在非尖峰時段放寬配額。

配額政策的變體「尖峰流量防範政策」可防止流量尖峰 (或爆量)，這類情況可能是因使用量突然增加、用戶端有錯誤或惡意攻擊所致。

您可以為存取 API Proxy 的所有應用程式設定相同配額，也可以根據下列因素設定不同的配額限制：

  • 包含 API Proxy 的產品
  • 要求 API 的應用程式
  • 應用程式開發人員
  • 上游服務
  • 許多其他條件
  • 任何可用條件的組合

請勿使用配額政策來防範整體流量遽增情形。如要這麼做，請使用 SpikeArrest 政策。

影片

這些影片會介紹如何透過配額政策管理配額：

簡介

動態配額

分散式和同步

訊息權重

日曆

滾動週期

Flexi

條件配額

流程變數

處理錯誤

配額政策類型

配額政策支援多種配額計數器啟動和重設方式。 您可以使用 <Quota> 元素上的 type 屬性定義要使用的項目，如下列範例所示：

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

type 的有效值包括：

  • calendar：根據明確的開始時間設定配額。系統會根據您設定的 <StartTime>、<Interval> 和 <TimeUnit> 值，重新整理每個應用程式的配額計數器。
  • rollingwindow：設定配額，使用「滾動時間範圍」判斷配額用量。使用 rollingwindow，透過 <Interval> 和 <TimeUnit> 元素決定時間範圍大小，例如 1 天。收到要求時，Apigee 會查看要求確切時間 (例如下午 5:01)，計算從前一天下午 5:01 到收到要求這段時間內的要求數量 (1 天)，並判斷配額是否已超出該時間範圍。
  • flexi：設定配額，讓計數器在收到應用程式的第一個要求訊息時開始計數，並根據 <Interval> 和 <TimeUnit> 值重設。

下表說明各類型的配額重設時間：

時間單位 類型
default (或空值) calendar flexi
分鐘 下一分鐘的開頭 <StartTime> 過後 1 分鐘 第一次要求後一分鐘
小時 下一個小時的整點 <StartTime>後一小時 發出第一個要求後一小時
天 當天格林威治標準時間午夜 <StartTime>後 24 小時 首次要求後 24 小時
週 每週結束時的週日格林威治標準時間午夜 <StartTime>過後一週 首次要求後一週
個月 當月最後一天的格林威治標準時間午夜 <StartTime>過後一個月 (28 天) 首次要求後一個月 (28 天)

您必須為 type="calendar" 指定 <StartTime> 的值。

下表未說明 rollingwindow 類型的計數何時會重設。 這是因為滾動式時間範圍配額的運作方式略有不同，會根據回溯時間範圍 (例如一小時或一天) 計算。如果是 rollingwindow 類型，計數器不會重設，但每次提出要求時都會重新計算。收到新要求時，政策會判斷過去一段時間是否已超出配額。

舉例來說，您可以定義兩小時的時段，允許 1000 個要求。下午 4:45 收到新要求。政策會計算過去兩小時內的配額數，也就是下午 2:45 以來的要求數。如果兩小時內未超過配額上限，系統就會允許要求。

一分鐘後，也就是下午 4:46，系統收到另一項要求。現在政策會計算下午 2:46 以來的配額數，判斷是否超過上限。

瞭解配額計數器

在 API Proxy 流程中執行配額政策時，配額計數器會遞增。當計數器達到上限時，系統會禁止與該計數器相關聯的 API 呼叫。視您為 API 產品使用的設定而定，配額政策可能會採用單一計數器，或多個獨立計數器。請務必瞭解使用多個計數器的情境，以及這些計數器的行為。

設定 API 產品的配額設定

API 產品可以在產品層級或個別作業層級指定配額設定，也可以同時在兩個層級指定。如果 API Proxy 包含在 API 產品中，您可以設定配額政策，使用該產品中定義的配額設定 (允許數量、時間單位和間隔)。最簡單的方法是透過 useQuotaConfigInAPIProduct 元素。或者，您也可以透過個別變數參照，在配額政策中參照這些設定。

配額的計算方式

根據預設，Apigee 會為 API 產品中定義的每個作業維護個別的配額計數器，並遵守下列規則：

  • 如果作業已定義配額，作業的配額設定會優先於產品層級定義的配額設定。
  • 如果作業未定義配額，系統會套用產品層級的配額設定。
  • 如果 API 產品未包含任何配額設定 (產品或作業層級皆無)，系統會套用配額政策中指定的允許次數、時間單位和間隔配額設定。

在所有情況下，Apigee 都會為 API 產品中定義的每項作業，維護個別的配額計數器。只要 API 呼叫符合作業，系統就會增加計數器。

設定配額政策，以使用 API 產品配額設定

如要設定配額政策，以便使用 Proxy 所屬 API 產品的配額設定，請按照下列步驟操作：

  1. 建立或更新 API 產品，並將 quotaCounterScope 屬性指定為 PRODUCT，以在 API 產品層級強制執行配額，或指定為 PROXY，以在 API Proxy 層級強制執行配額。
  2. 在 API 產品的所有 API Proxy 中，於要求流程中配額政策之前，新增 VerifyAPIKey 政策或具有 VerifyAccessToken 作業的 OAuthv2 政策。這些政策會為每個要求識別 API 產品。
  3. 設定配額政策，使用 API 產品中定義的限制，並加上 UseQuotaConfigInAPIProduct。

設定 API Proxy 層級的計數器

您可以設定 API 產品，在 API Proxy 範圍內維持配額計數。在這種情況下，API 產品層級指定的配額設定會套用至所有未指定配額的作業。這項設定的效果是在這個 API 產品的 API Proxy 層級建立計數器。

如要進行這項設定，您必須使用 /apiproducts Apigee API 建立或更新產品，並在建立或更新要求中，將 quotaCounterScope 屬性設為 PROXY。 透過 PROXY 設定，凡是與相同 Proxy 相關聯，且沒有專屬配額設定的 API 產品，只要要求符合其中一項作業定義，就會共用該 Proxy 的配額計數器。

在圖 1 中，作業 1 和 2 與 Proxy1 相關聯，作業 4 和 5 則與 Proxy3 相關聯。由於 API 產品中已設定 quotaCounterScope=PROXY，因此這些作業都會使用 API 產品層級的配額設定。與 Proxy1 相關聯的作業 1 和 2 使用共用計數器，與 Proxy3 相關聯的作業 4 和 5 則使用個別的共用計數器。作業 3 有自己的配額設定，因此無論 quotaCounterScope 屬性的值為何，都會使用自己的計數器。

圖 1：使用 quotaCounterScope 標記

如果未使用任何 API 產品，配額會如何計算？

如果 API Proxy 沒有相關聯的 API 產品，配額政策會維持單一計數器，無論您在 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 代理流程中，於多個位置使用相同的配額政策，可能會導致配額用盡的速度超出預期，這是「反模式簡介」一文所述的反模式。

或者，您可以在 API Proxy 中定義多項配額政策，並在每個流程中使用不同的政策。每項配額政策都會根據政策的 name 屬性，維護自己的計數器。

透過政策設定建立多個計數器

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

時間標記

所有配額時間都設為世界標準時間 (UTC) 時區。

配額時間標記遵循國際標準日期標記，如國際標準 ISO 8601 所定義。

日期定義為年、月和日，格式如下：YYYY-MM-DD。 舉例來說，2021-02-04 代表 2021 年 2 月 4 日。

一天中的時間定義為小時、分鐘和秒數，格式如下： hours:minutes:seconds。舉例來說，23:59:59 代表午夜前一秒。

請注意，有兩種標記方式 (00:00:00 和 24:00:00) 可用來區分與同一日期相關聯的兩個午夜。因此 2021-02-04 24:00:00 與 2021-02-05 00:00:00 的日期和時間相同。後者通常是偏好的標記方式。

從 API 產品設定取得配額設定

您可以在 API 產品設定中設定配額上限。這些限制不會自動強制執行配額。不過，您可以在配額政策中參照產品配額設定。為配額政策參照的產品設定配額，有以下優點：

  • 配額政策可以在 API 產品的所有 API Proxy 中使用統一設定。
  • 您可以對 API 產品的配額設定進行執行階段變更，而參照該值的配額政策會自動更新配額值。

如要進一步瞭解如何使用 API 產品的配額設定，請參閱上方的「動態配額」範例。

如要瞭解如何設定配額限制的 API 產品，請參閱「管理 API 產品」。

設定共用配額計數器

在簡單的情況下，配額政策會在初始要求處理期間，針對傳送至 API Proxy 的每項要求，將計數器遞增一次。在某些情況下，您可能想在初始處理傳入要求時檢查是否超出配額，但只在處理回應時遞增計數器。只有在上游或目標系統回應後，才能得知 API 呼叫的費用或權重，因此這種做法很合理。如果是 LLM API，費用可能取決於回應的詞元大小。如果是 BigQuery API，回應中的 total_slot_ms 可能會決定費用。

配額政策有三項元素：<SharedName>、<CountOnly> 和 <EnforceOnly>。只要搭配使用，您就能自訂配額政策，對傳入要求強制執行配額，並根據目標回應衍生資訊，累計配額用量。

舉例來說，假設您有一個以 LLM 做為目標的 API 代理，並希望每小時強制執行 100,000 個權杖的配額。大型語言模型回覆會提供 totalTokenCount 值。如要達成這個目標，請按照下列步驟操作：

  • 將配額政策附加至 ProxyEndpoint 要求流程，並將 <SharedName> 元素設為名稱值，以及將 <EnforceOnly> 元素設為 true。
  • 將 ExtractVariables 政策附加至 ProxyEndpoint 回應流程，從 LLM 目標收到的回應中擷取 totalTokenCount 值。
  • 將第二個配額政策附加至 ProxyEndpoint 回應流程，並將 <SharedName> 元素設為與第一個配額政策相同的名稱值，且將 <CountOnly> 元素設為 true。將 <MessageWeight> 元素設為使用擷取的 totalTokenCount 值。

如需共用計數器的使用範例，請參閱「範例」一節中的「共用計數器」。

範例

這些政策程式碼範例說明如何透過下列方式開始和結束配額週期：

更多動態配額

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

動態配額可讓您設定單一配額政策，根據傳遞至配額政策的資訊，強制執行不同的配額設定。在這個脈絡中，配額設定的另一個用語是「服務方案」。動態配額會檢查應用程式的服務方案，然後強制執行這些設定。

舉例來說，建立 API 產品時，您可以選擇設定允許的配額上限、時間單位和間隔。不過，在 API 產品上設定這些值，並不會強制在 API Proxy 中使用這些值。您也必須在 API Proxy 中新增配額政策，讀取這些值。詳情請參閱「建立 API 產品」。

在上述範例中，包含配額政策的 API Proxy 會使用名為 verify-api-key 的 VerifyAPIKey 政策，驗證要求中傳遞的 API 金鑰。接著，配額政策會存取 VerifyAPIKey 政策中的流程變數，讀取 API 產品上設定的配額值。

您也可以在個別開發人員或應用程式上設定自訂屬性，然後在配額政策中讀取這些值。舉例來說，如要為每位開發人員設定不同的配額值，請在開發人員上設定自訂屬性，其中包含限制、時間單位和間隔。接著，您可以在配額政策中參照這些值，如下所示：

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

這個範例也會使用 VerifyAPIKey 流程變數，參照開發人員設定的自訂屬性。

您可以使用任何變數設定配額政策的參數。這些變數可能來自：

  • 流程變數
  • API 產品、應用程式或開發人員的屬性
  • 鍵/值對應 (KVM)
  • 標頭、查詢參數、表單參數等

您可以為每個 API Proxy 新增配額政策，該政策可參照所有其他 Proxy 中所有其他配額政策的相同變數，也可以參照該政策和 Proxy 專屬的變數。

開始時間

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2021-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

如果配額的 type 設為 calendar，您必須定義明確的 <StartTime> 值。時間值為 GMT 時間，而非當地時間。如果未提供 <StartTime> 值給 calendar 類型的政策，Apigee 會發出錯誤。

系統會根據 <StartTime>、<Interval> 和 <TimeUnit> 值，重新整理每個應用程式的配額計數器。以這個例子來說，配額會在 2021 年 2 月 18 日格林威治標準時間上午 10:30 開始計算，並每 5 小時重新計算一次。因此，下一次更新時間為 2021 年 2 月 18 日下午 3 點 30 分 (格林威治標準時間)。

存取計數器

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

API Proxy 可存取配額政策設定的流程變數。您可以在 API 代理程式中存取這些流程變數，執行條件式處理、監控政策是否即將達到配額限制、將目前的配額計數器傳回應用程式，或是基於其他原因。

由於存取政策的流程變數是根據政策的 name 屬性，因此對於上述名為 <Quota> 的政策，您會以以下形式存取其流程變數：

  • ratelimit.QuotaPolicy.allowed.count：允許的金額。
  • ratelimit.QuotaPolicy.used.count：目前的計數器值。
  • ratelimit.QuotaPolicy.expiry.time：計數器重設時的世界協調時間。

如要存取其他流程變數，請參閱下文。

舉例來說，您可以使用下列 AssignMessage 政策，以回應標頭的形式傳回配額流程變數的值：

<AssignMessage 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>

共用計數器

以下範例說明如何為 API Proxy 設定共用計數器，其中配額計數器也會在目標回應為 HTTP 狀態 200 時遞增。由於這兩項配額政策使用相同的 <SharedName> 值，因此會共用同一個配額計數器。詳情請參閱「設定共用配額計數器」。

ProxyEndpoint 設定範例： 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>Quota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>EV-Token-Count</Name>
      </Step>
      <Step>
        <Name>Quota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

第一個配額政策範例：

<Quota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</Quota>

ExtractVariable 政策範例：

<ExtractVariables name='EV-Token-Count'>
  <Source>response</Source>
  <VariablePrefix>extracted</VariablePrefix>
  <JSONPayload>
    <Variable name='tokenCount'>
      <JSONPath>$[1].usageMetadata.totalTokenCount</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

第二個配額政策範例：

<Quota name="Quota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first Quota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <MessageWeight ref="extracted.tokenCount"/>
</Quota>

首次要求

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

使用這個範例程式碼，強制每小時配額為 10,000 次呼叫。這項政策會在每個整點重設配額計數器。如果計數器在一小時結束前達到 10,000 次通話配額，系統會拒絕超過 10,000 次的通話。

舉例來說，如果計數器從 2021-07-08 07:00:00 開始，則會在 2021-07-08 08:00:00 (開始時間後 1 小時) 重設為 0。如果系統在 2021-07-08 07:35:28 收到第一封訊息，且訊息數量在 2021-07-08 08:00:00 前達到 10,000 則，系統會拒絕超過該數量的呼叫，直到每小時開始時重設數量為止。

計數器重設時間取決於 <Interval> 和 <TimeUnit> 的組合。舉例來說，如果您將 <Interval> 設為 12，並將 <TimeUnit> 設為小時，則計數器每 12 小時就會重設一次。您可以將 <TimeUnit> 設為分鐘、小時、天、週或月。

您可以在 API Proxy 的多個位置參照這項政策。舉例來說，您可以將其放在 Proxy PreFlow 中，以便在每個要求上執行。或者，您也可以將其放在 API Proxy 中的多個流程。如果您在 Proxy 中的多個位置使用這項政策，系統會維護單一計數器，並由政策的所有執行個體更新。

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

設定 ID

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

根據預設，配額政策會為 API Proxy 定義單一計數器，無論要求來源為何。或者，您也可以搭配配額政策使用 <Identifier> 屬性，根據 <Identifier> 屬性的值維護個別計數器。

舉例來說，您可以使用 <Identifier> 標記，為每個用戶端 ID 定義個別計數器。在對 Proxy 的要求中，用戶端應用程式會傳遞包含 clientID 的標頭，如上例所示。

您可以為 <Identifier> 屬性指定任何流程變數。舉例來說，您可以指定名為 id 的查詢參數包含專屬 ID：

<Identifier ref="request.queryparam.id"/>

如果您使用 VerifyAPIKey 政策驗證 API 金鑰，或使用 OAuth 權杖的 OAuthV2 政策，可以利用 API 金鑰或權杖中的資訊，為相同的配額政策定義個別計數器。舉例來說，下列 <Identifier> 元素會使用名為 verify-api-key 的 VerifyAPIKey 政策的 client_id 流程變數：

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

每個不重複的 client_id 值現在都會在配額政策中定義自己的計數器。

類別

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

您可以使用以類別為準的配額計數，動態設定配額限制。在本例中，配額限制取決於隨每項要求傳遞的 developer_segment 標頭值。該變數的值可以是 platinum 或 silver。如果標頭包含無效值，政策會傳回配額違規錯誤。

<Quota> 元素

以下是 <Quota> 的屬性和子項元素。請注意，部分元素組合互斥或非必要。如需特定用法，請參閱範例。

當名為 my-verify-key-policy 的 VerifyAPIKey 政策用於檢查要求中的應用程式 API 金鑰時，預設會提供下列 verifyapikey.my-verify-key-policy.apiproduct.* 變數。變數值來自與金鑰相關聯的 API 產品配額設定，如「從 API 產品設定取得配額設定」一文所述。

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

這項政策專屬的屬性如下：

屬性 說明 預設 狀態
類型

設定「配額政策類型」，決定配額計數器檢查配額用量以及重設配額的時間和方式。

如果未設定 type，計數器會從分鐘/小時/天/週/月的第一個時間點開始計數。

有效值包括：

  • calendar
  • rollingwindow
  • flexi

如需各類型的完整說明，請參閱「配額政策類型」。

 不適用 選用

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

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<Allow>

指定配額的數量限制。如果政策的計數器達到這個限制值，系統會拒絕後續呼叫，直到計數器重設為止。

也可以包含 <Class> 元素，根據流程變數設定 <Allow> 元素的條件。

預設值 不適用
必填與否 選用
類型 整數或複數類型
父項元素 <Quota>
子元素 <Class>

以下三種方式可設定 <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 的值。

您也可以指定 <Class> 元素做為 <Allow> 的子項，根據流程變數決定政策允許的計數。Apigee 會將流程變數的值與 <Allow> 元素的 class 屬性相符，如下所示：

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

下表列出 <Allow> 的屬性：

屬性 說明 預設 狀態
數量

用於指定配額的訊息數量。

舉例來說，如果 count 屬性值為 100、Interval 為 1，且 TimeUnit 為「month」，則配額為每月 100 則訊息。

 2000 選用
countRef

用於指定含有配額訊息計數的流程變數。 countRef 的優先順序高於 count 屬性。

 無 選用

<Class>

根據流程變數的值，有條件地設定 <Allow> 元素的值。對於 <Class> 的每個不同 <Allow> 子項標記，政策會維持不同的計數器。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <Allow>
子元素 <Allow> (<Class> 的子項)

如要使用 <Class> 元素，請使用 ref 屬性，為 <Class> 元素指定流程變數。Apigee 接著會使用流程變數的值選取其中一個 <Allow> 子元素，判斷政策允許的計數。Apigee 會將流程變數的值與 <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。如果查詢參數含有無效值，政策會傳回配額違規錯誤。

下表列出 <Class> 的屬性：

屬性 說明 預設 狀態
ref 用於指定包含配額配額類別的流程變數。 無 必填

<Allow> (<Class> 的子項)

指定 <Class> 元素定義的配額計數器限制。對於 <Class> 的每個不同 <Allow> 子項標記，政策會維護不同的計數器。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <Class>
子元素 無

例如：

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow count="5000"/>
        <Allow count="1000"/>
      </Class>
    </Allow>

在這個範例中，配額政策會維護兩個配額計數器，分別命名為 peak_time 和 off_peak_time。使用哪個參數取決於傳遞的查詢參數，如 <Class> 範例所示。

下表列出 <Allow> 的屬性：

屬性 說明 預設 狀態
類別 定義配額計數器的名稱。 無 必填
數量 指定計數器的配額限制。 無 必填

<Interval>

指定計算配額的時間間隔。

預設值 不適用
必填與否 必填
類型 整數
父項元素 <Quota>
子元素 無

指定與您指定的 <TimeUnit> 元素 (分鐘、小時、天、週或月) 配對的整數 (例如 1、2、5、60 等)，藉此決定 Apigee 計算配額用量的時間範圍。

舉例來說，間隔為 24，且 <TimeUnit> 為 hour，表示系統會在 24 小時內計算配額。

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

下表列出 <Interval> 的屬性：

屬性 說明 預設 狀態
ref

用於指定包含配額間隔的流程變數。ref 的優先順序高於明確間隔值。如果同時指定參照和值，系統會優先採用參照。 如果 ref 無法在執行階段解析，則會使用該值。

 無 選用

<TimeUnit>

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

預設值 不適用
必填與否 必填
類型 字串
父項元素 <Quota>
子元素 無

選取 minute、hour、day、week、month 或 year。

舉例來說，Interval 為 24，TimeUnit 為 hour 代表配額會在 24 小時內計算。

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
預設值： 無
外觀狀態： 必填
類型： 字串

下表列出 <TimeUnit> 的屬性：

屬性 說明 預設 狀態
ref 指定包含配額時間單位的流程變數。ref 的優先順序高於明確間隔值。如果 ref 在執行階段無法解析，系統就會使用間隔值。 無 選用

<StartTime>

如果 type 設為 calendar，則無論是否收到任何應用程式的要求，配額計數器都會從指定日期和時間開始計數。

預設值 不適用
必填與否 選填 (如果 type 設為 calendar，則為必填)
類型 採用 ISO 8601 日期和時間格式的字串
父項元素 <Quota>
子元素 無

例如：

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

<Distributed>

決定 Apigee 是否使用一或多個節點處理要求。

預設值 false
必填與否 選用
類型 布林值
父項元素 <Quota>
子元素 無

設為 true，指定政策應維護中央計數器，並在所有節點間持續同步處理。節點可跨可用區和/或區域。

如果您使用預設值 false，則可能超出配額，因為系統不會共用每個節點的計數：

<Distributed>false</Distributed>

如要確保計數器同步處理，並在每次要求時更新，請將 <Distributed> 和 <Synchronous> 設為 true：

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

判斷是否要同步更新分散式配額計數器。

預設值 false
必填與否 選用
類型 布林值
父項元素 <Quota>
子元素 無

設為 true 可同步更新分散式配額計數器。也就是說，系統會在檢查 API 要求配額時，同時更新計數器。如果絕對不能允許任何 API 呼叫超出配額，請設為 true。

設為 false，以非同步方式更新配額計數器。也就是說，視中央存放區的配額計數器非同步更新時間而定，部分超出配額的 API 呼叫可能會通過。不過，您不會面臨與同步更新相關的潛在效能影響。

預設的非同步更新間隔為 10 秒。請使用 <AsynchronousConfiguration> 元素設定這項非同步行為。

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

如果政策設定元素 <Synchronous> 不存在，或存在但設為 false，則設定分散式配額計數器之間的同步間隔。如果 <Synchronous> 設為 true，Apigee 會忽略這個元素。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <Quota>
子元素 <SyncIntervalInSeconds>
<SyncMessageCount>

您可以使用 <SyncIntervalInSeconds> 或 <SyncMessageCount> 子元素指定同步行為。使用其中一個或兩個元素。例如，假設使用者要求系統 將文字從英文翻譯成法文

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

或

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • 如果只有 <SyncIntervalInSeconds>，配額會每 N 秒同步一次，其中 N 是元素中指定的值，無論處理了多少訊息都一樣。
  • 如果只有 <SyncMessageCount>，配額會每 M 則訊息同步一次 (M 是元素中指定的值)，或每 10 秒同步一次 (以先發生者為準)。
  • 如果兩項元素都存在，系統會每 M 則訊息或每 N 秒同步配額 (以先發生者為準)。
  • 如果沒有 <AsynchronousConfiguration> 或任何子項元素，配額會每 10 秒同步一次，無論處理了多少訊息。

<SyncIntervalInSeconds>

覆寫預設行為，也就是在間隔 10 秒後執行非同步更新。

預設值 10 秒
必填與否 選用
類型 整數
父項元素 <AsynchronousConfiguration>
子元素 無
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

如「限制」一節所述，同步間隔必須 >= 10 秒。

<SyncMessageCount>

指定要處理的要求數量，之後再同步配額計數器。

預設值 不適用
必填與否 選用
類型 整數
父項元素 <AsynchronousConfiguration>
子元素 無
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

使用這個範例中的設定時，每個節點的配額計數會在每 5 個要求或每 10 秒後同步處理 (以先發生者為準)。

<Identifier>

設定政策，根據流程變數建立不重複的計數器。

預設值 不適用
必填與否 選用
類型 字串
父項元素 <Quota>
子元素 無

透過「ID」元素，您可以根據流程變數中的值，將通話次數分配到不同的儲存區。舉例來說，您可以使用 developer.id 變數 (在 VerifyAPIKey 政策後填入)，對每個特定開發人員建立的所有應用程式例項強制執行配額限制，也可以使用 client_id 對每個特定應用程式強制執行配額限制。後者的設定如下：

<Identifier ref="client_id"/>

您可以參照您可能使用 AssignMessage 政策或 JavaScript 政策設定的自訂變數，也可以參照隱含設定的變數，例如 VerifyAPIKey 政策或 VerifyJWT 政策設定的變數。如要進一步瞭解變數，請參閱「使用流程變數」；如需 Apigee 定義的知名變數清單，請參閱「流程變數參考資料」。

如未使用這個元素，政策會將所有通話次數分配到特定配額政策的單一計數器。

如要瞭解這個元素，請參閱「未指定 ID 時，配額政策的運作方式為何？」一文。

下表說明 <Identifier> 的屬性：

屬性 說明 預設 狀態
ref

指定用於要求的計數器流程變數。變數可以參照 HTTP 標頭、查詢參數、表單參數、訊息內容的元素，或是其他值，以識別如何分配通話次數。

client_id 通常用做變數。client_id 也稱為 API 金鑰或消費者金鑰，是在應用程式於 Apigee 上的機構中註冊時產生。如果已為 API 啟用 API 金鑰或 OAuth 授權政策，即可使用這個 ID。

 不適用 選用

<MessageWeight>

指定配額用途的每則訊息費用。根據 API 要求的內容或呼叫價值，使用這個元素為 API 要求指派不同的影響。

預設值 不適用
必填與否 選用
類型 整數
父項元素 <Quota>
子元素 無

舉例來說，當 Apigee 管理大型語言模型 (LLM) API 時，您可以將要求或回應中的權杖數量 (或兩者) 設為 <MessageWeight>。

或者，如要將 POST 訊息的費用設為 GET 訊息的兩倍，請將 <MessageWeight> 設為 2 (POST) 和 1 (GET)。假設配額為每分鐘 10 則訊息，且 Proxy 在前 35 秒處理了 5 個 POST 要求。在計數器重設前，Proxy 會拒絕任何額外要求 (POST 或 GET)。

代表 <MessageWeight> 的值必須使用流程變數指定，且可從 HTTP 標頭、查詢參數、XML 或 JSON 要求酬載，或任何其他流程變數中擷取。舉例來說，您可以將回應酬載中的值擷取到名為 extracted.message_weight 的變數中，然後用於 <MessageWeight>：

<MessageWeight ref="extracted.message_weight"/>

如果流程變數解析為 0，要求就不會影響計數器。

<UseQuotaConfigInAPIProduct>

定義 API 產品的配額設定，例如時間單位、間隔和允許上限。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <Quota>
子元素 <DefaultConfig>

如果將 <UseQuotaConfigInAPIProduct> 元素新增至配額政策，Apigee 會忽略 <Quota> 的任何 <Allow>、<Interval> 和 <TimeUnit> 子元素。

<UseQuotaConfigInAPIProduct> 元素只是預設設定的容器，您可以使用 <DefaultConfig> 元素定義預設設定，如下列範例所示：

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

您可以使用 stepName 屬性，在流程中參照 VerifyAPIKey 政策或 OAuthv2 政策的 ValidateToken 政策作業。

下表說明 <UseQuotaConfigInAPIProduct> 的屬性：

屬性 說明 預設 狀態
stepName 識別流程中的驗證政策名稱。目標可以是 VerifyAPIKey 政策或 OAuthv2 政策。 不適用 必填

如要瞭解詳情，請參考下列資源：

<DefaultConfig>

包含 API 產品配額的預設值。定義 <DefaultConfig> 時，必須提供所有三個子項元素。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <UseQuotaConfigInAPIProduct>
子元素 <Allow>
<Interval>
<TimeUnit>

您可以在 API 產品的作業中定義這些值 (透過 UI 或 API 產品 API)，也可以在配額政策中定義。但如果這麼做，API 產品的設定會優先採用，配額政策的設定則會遭到忽略。

這個元素的語法如下：

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

以下範例指定每週配額為 10,000：

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

如要瞭解詳情，請參考下列資源：

<SharedName>

將這項配額政策識別為「共用」。API Proxy 中具有相同 <SharedName> 值的配額政策，會共用相同的基礎配額計數器。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值 不適用
必填與否 選用
類型 字串
父項元素 <Quota>
子元素 無

<CountOnly>

在 ProxyEndpoint 回應流程的步驟中，將這個元素設為 true，然後放置配額政策，即可在超過配額限制時遞增基礎配額計數器，而不必將錯誤傳回給用戶端。如果存在這個元素，則 <SharedName> 元素也必須存在，且 <EnforceOnly> 元素不得存在。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值 false
必填與否 選用
類型 布林值
父項元素 <Quota>
子元素 無

<EnforceOnly>

在 API Proxy 的要求流程中，將這個元素設為 true，即可放置配額政策，強制執行配額，而不遞增配額計數器。這項設定可根據訊息權重延後強制執行速率限制，而訊息權重只能在回應流程中得知。如果存在這個元素，則 <SharedName> 也必須存在，且 <CountOnly> 元素不得存在。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值 false
必填與否 選用
類型 布林值
父項元素 <Quota>
子元素 無

流程變數

配額政策執行時，系統會自動填入下列預先定義的流程變數。詳情請參閱「流程變數參考資料」。

變數 類型 權限 說明
ratelimit.{policy_name}.allowed.count Long 唯讀 傳回允許的配額數量。
ratelimit.{policy_name}.used.count Long 唯讀 傳回配額間隔內目前使用的配額。
ratelimit.{policy_name}.available.count Long 唯讀 傳回配額間隔內的可用配額數。
ratelimit.{policy_name}.exceed.count Long 唯讀 超過配額時，傳回 1。
ratelimit.{policy_name}.total.exceed.count Long 唯讀 超過配額時，傳回 1。
ratelimit.{policy_name}.expiry.time Long 唯讀

傳回 UTC 時間 (以毫秒為單位)，用於判斷配額到期時間和新配額間隔的開始時間。

如果配額政策的類型為 rollingwindow，這個值無效，因為配額間隔永不過期。
ratelimit.{policy_name}.identifier 字串 唯讀 傳回附加至政策的 (用戶端) 參照 ID
ratelimit.{policy_name}.class 字串 唯讀 傳回與用戶端 ID 相關聯的類別
ratelimit.{policy_name}.class.allowed.count Long 唯讀 傳回類別中定義的允許配額數
ratelimit.{policy_name}.class.used.count Long 唯讀 傳回類別中已使用的配額
ratelimit.{policy_name}.class.available.count Long 唯讀 傳回類別中的可用配額數
ratelimit.{policy_name}.class.exceed.count Long 唯讀 傳回目前配額間隔內，類別中超出限制的要求數
ratelimit.{policy_name}.class.total.exceed.count Long 唯讀 傳回所有配額間隔中，超過類別限制的要求總數，因此是所有配額間隔的 class.exceed.count 總和。
ratelimit.{policy_name}.failed 布林值 唯讀

指出政策是否失敗 (true 或 false)。

錯誤參考資料

本節說明 Apigee 在這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息，以及設定的錯誤變數。如果您要開發用來處理錯誤的錯誤規則，就必須瞭解這項資訊。如要瞭解詳情，請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤碼 HTTP 狀態 原因 修正
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 如果 <Interval> 元素未在 Quota 政策中定義，就會發生這種情況。這個元素為必填，用於指定配額適用的時間間隔。時間間隔可以是分鐘、小時、天、週或月，如 <TimeUnit> 元素所定義。
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 如果 <TimeUnit> 元素未在 Quota 政策中定義，就會發生這種情況。這個元素為必填，用於指定適用於配額的時間單位。時間間隔可以分鐘、小時、天、週或月為單位。
policies.ratelimit.InvalidMessageWeight 500 如果透過流程變數指定的 <MessageWeight> 元素值無效 (非整數值)，就會發生這個錯誤。
policies.ratelimit.QuotaViolation 500 超出配額限制。 不適用

部署錯誤

錯誤名稱 原因 修正
InvalidQuotaInterval 如果 <Interval> 元素中指定的配額間隔不是整數，API 代理項目的部署作業就會失敗。舉例來說，如果 <Interval> 元素中指定的配額間隔為 0.1，API Proxy 的部署作業就會失敗。
InvalidQuotaTimeUnit 如果 <TimeUnit> 元素中指定的時間單位不受支援，API Proxy 部署作業就會失敗。支援的時間單位為 minute、hour、day、week 和 month。
InvalidQuotaType 如果 <Quota> 元素中 type 屬性指定的配額類型無效，API Proxy 部署作業就會失敗。支援的配額類型為 default、calendar、flexi 和 rollingwindow。
InvalidStartTime 如果 <StartTime> 元素中指定的時間格式無效，API Proxy 的部署作業就會失敗。有效格式為 yyyy-MM-dd HH:mm:ss，這是 ISO 8601 日期和時間格式。舉例來說，如果 <StartTime> 元素中指定的時間是 7-16-2017 12:00:00，API Proxy 的部署作業就會失敗。
StartTimeNotSupported 如果指定的 <StartTime> 元素配額類型不是 calendar 類型，API Proxy 部署作業就會失敗。<StartTime> 元素僅支援 calendar 配額類型。舉例來說，如果 type 屬性在 <Quota> 元素中設為 flexi 或 rolling window，API Proxy 的部署作業就會失敗。
InvalidSynchronizeIntervalForAsyncConfiguration 如果 Quota 政策中 <AsynchronousConfiguration> 元素內的 <SyncIntervalInSeconds> 元素指定值小於零，API Proxy 部署作業就會失敗。
InvalidAsynchronizeConfigurationForSynchronousQuota 如果 Quota 政策中的 <AsynchronousConfiguration> 元素值設為 true，且該政策也使用 <AsynchronousConfiguration> 元素定義非同步設定，則 API 代理伺服器部署作業會失敗。

錯誤變數

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

變數 地點 範例
fault.name="fault_name" fault_name 是故障名稱，如上方的「執行階段錯誤」表格所示。故障名稱是故障代碼的最後一部分。 fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name 是使用者指定的政策名稱，該政策擲回了錯誤。 ratelimit.QT-QuotaPolicy.failed = true

錯誤回應範例

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

比較配額和尖峰流量防範政策