配額政策

本頁適用於 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 點 1 分)，計算在該時間與前一天下午 5 點 1 分 (1 天) 之間傳入的要求數量，並判斷是否在該時間範圍內超出配額。
• flexi：設定配額，讓計數器在從應用程式收到第一個要求訊息時開始運作，並根據 <Interval> 和 <TimeUnit> 值重設。

下表說明各類型配額的重新計算時間：

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

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

舉例來說，您可以定義兩小時的時間範圍，允許 1000 個要求。新的要求會在下午 4 點 45 分進來。政策會計算過去兩小時的配額計數，也就是下午 2 點 45 分後的要求次數。如果在兩小時內未超過配額上限，系統就會允許要求。

一分鐘後，也就是下午 4 點 46 分，另一個要求傳入。政策現在會計算下午 2 點 46 分以後的配額計數，判斷是否已超過限制。

瞭解配額計數器

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

API 產品的配額計算方式

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

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

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

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

設定 API Proxy 層級計數器

您可以設定 API 產品，在 API Proxy 範圍內維持配額計數。在這種情況下，所有未指定專屬配額的作業都會共用在 API 產品層級指定的配額設定。這項設定的效果是在 API 代理程式層級為此 API 產品建立全域計數器。

如要完成這項設定，您必須使用 /apiproducts Apigee API 建立或更新產品，並在建立或更新要求中將 quotaCountScope 屬性設為 PROXY。在 PROXY 設定中，為 API 產品定義的所有作業都會與同一個 Proxy 相關聯，且不具備專屬計數器，因此會在 API 產品層級共用相同的配額計數器組合。

在圖 1 中，作業 1 和 2 與 Proxy1 相關聯，作業 4 和 5 則與 Proxy3 相關聯。由於 quotaCounterScope=PROXY 是在 API 產品中設定，因此每個作業都會共用 API 產品層級的配額設定。請注意，雖然這些作業共用相同的配額設定，但會根據其委派作業關聯使用不同的計數器。另一方面，作業 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 代表午夜前 1 秒的時間。

請注意，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 的要求，配額政策就會將計數器加 1。在某些情況下，您可能需要檢查在處理傳入要求的初始階段是否超過配額，但只在回應處理期間遞增計數器。只有在上游或目標系統回應後，才能得知 API 呼叫的費用或權重，這時就適合使用此做法。在 LLM API 的情況下，費用可能會由符記中的回應大小決定。在 BigQuery API 的情況下，回應中的 total_slot_ms 可能會決定費用。

三個配額政策元素 (<SharedName>、<CountOnly> 和 <EnforceOnly>) 可搭配使用，讓您自訂配額政策，對傳入要求強制執行配額，並根據目標回應衍生的資訊累積計數。

舉例來說，假設您有一個使用 LLM 做為目標的 API 代理程式，且希望強制執行每小時 100,000 個符記的配額。LLM 回應會提供 totalTokenCount 值。如要達成這一目標，請執行下列操作：

• 將配額政策附加至 ProxyEndpoint 要求流程，並將 <SharedName> 元素設為名稱值，<EnforceOnly> 元素設為 true。
• 在 ProxyEndpoint 回應流程中，附加 ExtractVariables 政策，從 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> 的屬性和子項元素。請注意，某些元素組合互斥或不必要。請參閱範例，瞭解具體用法。

當您使用名為 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>

下列屬性僅適用於這項政策：

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

<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> 元素，請使用 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> 的屬性：

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

指定計算配額的時間範圍數量。

可用於指定整數 (例如 1、2、5、60 等)，並與您指定的 <TimeUnit> 元素 (分鐘、小時、天、週或月) 搭配使用，以便決定 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>

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

您可以透過「Identifier」元素，將呼叫次數分配給由資料流變數中的值定義的不同值組。舉例來說，您可以使用 developer.id 變數 (會在 VerifyAPIKey 政策後填入)，為每位特定開發人員建立的所有應用程式所有例項強制執行一個配額限制，或是使用 client_id 為每個特定應用程式強制執行配額限制。後者的設定如下所示：

<Identifier ref="client_id"/>

您可以參照您可能會使用 AssignMessage 政策或 JavaScript 政策設定的自訂變數，或是隱含設定的變數，例如由 VerifyAPIKey 政策或 VerifyJWT 政策設定的變數。如要進一步瞭解變數，請參閱「使用 Flow 變數」一文；如要查看 Apigee 定義的常用變數清單，請參閱「Flow 變數參考資料」。

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

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

下表說明 <Identifier> 的屬性：

<MessageWeight>

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

舉例來說，當 Apigee 管理大型語言模型 (LLM) API 時，您可以使用要求或回應中的符記數量 (或兩者皆可) 做為 <MessageWeight>。

或者，如果您想將 POST 訊息的費用計算為 GET 訊息的兩倍，請將 <MessageWeight> 設為 POST 的 2 和 GET 的 1。假設配額為每分鐘 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 代理程式的要求流程中，放置配額政策，並將此元素設為 true，即可強制執行配額，而不增加配額計數器。這項設定可讓您根據訊息權重 (僅在回應流程中可知) 延後執行費率限制。如果使用這個元素，就必須一併使用 <SharedName>，且不得使用 <CountOnly> 元素。

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

流程變數

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

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 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 政策

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