配額政策

本頁內容適用於 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 時，您可以根據要求或回應中的權杖數量 (或兩者) 實施速率限制。此外，配額限制本身可以是動態的，也就是說，您可以在系統忙碌時強制執行更嚴格的配額，或在非尖峰時段放寬配額。

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

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

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

請勿使用配額政策來防範整體流量遽增情形。如要達到這個目的，請使用 SpikeArrest 政策。

影片

這些影片會介紹配額政策的配額管理功能：

配額政策類型

配額政策支援多種配額計數器啟動和重設方式。 您可以使用 <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> 值重設。

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

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

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

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

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

瞭解配額計數器

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

API 產品的配額計算方式

如果 API 產品包含 API Proxy，您可以設定配額政策，使用該產品中定義的配額規則。API 產品可以在產品層級或個別作業層級指定配額規則。

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

• 如果作業已定義配額，作業的配額規則優先於產品層級定義的配額規則。系統會為每項作業建立個別的配額計數器。對作業路徑的任何 API 呼叫都會增加計數器。
• 如果作業未定義配額，系統會套用產品層級配額規則；不過，系統仍會為作業維護個別配額計數器。請務必瞭解，即使配額規則取自產品層級定義，作業仍會維持自己的計數器。
• 如果 API 產品未納入任何配額定義 (產品或作業層級皆無)，系統會套用政策中指定的配額規則；不過，在這種情況下，系統也會為 API 產品中的每個作業維護個別的配額計數器。

以下各節將詳細說明計數器選項和行為。

設定 API Proxy 層級的計數器

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

如要進行這項設定，您必須使用 /apiproducts Apigee API 建立或更新產品，並在建立或更新要求中，將 quotaCountScope 屬性設為 PROXY。 透過 PROXY 設定，與相同 Proxy 相關聯且沒有自己計數器的 API 產品所定義的所有作業，都會共用在 API 產品層級設定的配額計數器。

在圖 1 中，作業 1 和 2 與 Proxy1 相關聯，作業 4 和 5 則與 Proxy3 相關聯。由於 API 產品中已設定 quotaCounterScope=PROXY，因此這些作業會共用 API 產品層級的配額設定。請注意，雖然這些作業共用相同的配額設定，但會根據 Proxy 關聯使用不同的計數器。另一方面，作業 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>

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

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

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

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

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

<Quota> 元素

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

使用 VerifyAPIKey 政策 (稱為 my-verify-key-policy) 檢查要求中的應用程式 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>

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<Allow>

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

也可以包含 <Class> 元素，根據流程變數設定 <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 的值。

您也可以指定 <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> 的屬性：

<Class>

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

如要使用 <Class> 元素，請使用 <Class> 元素的 ref 屬性指定流程變數。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> 的屬性：

<Allow> (<Class> 的子項)

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

例如：

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

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

下表列出 <Allow> 的屬性：

<Interval>

指定計算配額的時間週期數。

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

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

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

下表列出 <Interval> 的屬性：

<TimeUnit>

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

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

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

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

下表列出 <TimeUnit> 的屬性：

<StartTime>

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

例如：

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

<Distributed>

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

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

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

<Distributed>false</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，則設定分散式配額計數器之間的同步間隔。如果 <Synchronous> 設為 true，Apigee 會忽略這個元素。

您可以使用 <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 秒後執行非同步更新。

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

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

<SyncMessageCount>

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

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

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

<Identifier>

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

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

<Identifier ref="client_id"/>

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

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

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

下表說明 <Identifier> 的屬性：

<MessageWeight>

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

舉例來說，當 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 產品的配額設定，例如時間單位、間隔和允許上限。

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

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

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

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

下表說明 <UseQuotaConfigInAPIProduct> 的屬性：

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

• <DefaultConfig>
• 什麼是 API 產品？
• 管理 API 產品

<DefaultConfig>

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

您可以在 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>

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

• 什麼是 API 產品？
• 管理 API 產品

<SharedName>

將這項配額政策識別為「共用」。API Proxy 中具有相同 <SharedName> 值的配額政策，都會共用相同的基礎配額計數器。如果存在這個元素，則必須一併提供 <EnforceOnly> 或 <CountOnly> 元素。

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

<CountOnly>

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

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

<EnforceOnly>

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

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

流程變數

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

錯誤參考資料

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

執行階段錯誤

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

部署錯誤

錯誤變數

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

錯誤回應範例

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

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