Quota ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちらをご覧ください。

概要

割り当ては、API プロキシが一定の期間（分、時間、日、週、月単位）に処理できるリクエストメッセージの割り当て量です。Quota ポリシーは、API プロキシによって受信したリクエストの数を集計するカウンタを管理します。この機能により、API プロバイダで一定の時間内にアプリで行われた API 呼び出しの数に上限を適用できます。たとえば、Quota ポリシーを使用して、アプリのリクエストを 1 分あたり 1 回に制限したり、1 か月に 10,000 回に制限したりできます。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

たとえば、Quota が 1 か月あたり 10,000 件のメッセージに定義されている場合、10,000 番目のメッセージより後はレート制限が開始されます。10,000 件のメッセージがその期間の最初の日にカウントされたか、最後の日にカウントされたかは関係ありません。指定した期間の終了時に割り当てカウンタが自動的にリセットされるか、ResetQuota ポリシーを使用して明示的に割り当てがリセットされるまで、追加のリクエストは許可されません。

Quota ポリシーのバリエーションである SpikeArrest ポリシーを使用すると、突然の使用量の増加、バグの多いクライアント、悪意のある攻撃によって発生する可能性のあるトラフィック急増（バースト）を防ぐことができます。

Quota ポリシーを使用して、API プロキシで一定の期間（分、時間、日、週、月単位）に許可されるリクエストメッセージの数を構成します。API プロキシにアクセスするすべてのアプリに同じ割り当てを設定することも、次の条件に基づいて設定することもできます。

API プロキシを含むプロダクト
API をリクエストするアプリ
アプリデベロッパー
その他の多数の基準

Quota ポリシーは、全体的なトラフィックの急増を防ぐことを目的として使用しないでください。その場合は SpikeArrest ポリシーを使用します。

動画

次の動画では、Quota ポリシーで割り当てを管理する方法を説明しています。

はじめに

動的割り当て

分散と同期

メッセージウェイト

カレンダー

ローリングウィンドウ

Flexi

条件付き割り当て

フロー変数

エラー処理

Quota ポリシーのタイプ

Quota ポリシーは、割り当てカウンタの開始とリセットの方法を複数サポートしています。どの方法を使用するかは、次の例に示すように、<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> の値に基づいてリセットする割り当てを構成します。

次の表は、各タイプの割り当てのリセットについて説明したものです。

時間単位	型
時間単位	`default`（または null）	`calendar`	`flexi`
分	次の 1 分間の開始	`<StartTime>` から 1 分後	最初のリクエストの 1 分後
時間	次の 1 時間の開始	`<StartTime>` から 1 時間後	最初のリクエストの 1 時間後
日	現在の日付の深夜（GMT）	`<StartTime>` から 24 時間後	最初のリクエストの 24 時間後
週	週の終わりの日曜日の深夜（GMT）	`<StartTime>` から 1 週間後	最初のリクエストの 1 週間後
月	月の最終日の深夜（GMT）	`<StartTime>` の 1 か月（28 日）後	最初のリクエストの 1 か月（28 日）後

注: このポリシーでは、時間単位として second もサポートされます。ただし、second は、Distributed=false で定義されている、非分散カウンタでのみサポートされます。second を使用する代わりに、SpikeArrest ポリシーを使用して、リクエストトラフィックの急増を秒レベルで制限することをおすすめします。

type="calendar" には、<StartTime> の値を指定する必要があります。

この表には、rollingwindow タイプの値は記載されていません。ローリングウィンドウ割り当ては、1 時間や 1 日のウィンドウなど、割り当て時間枠の長さを設定することによって機能します。新しいリクエストを受信すると、過去の時間枠内で割り当てを超過したかどうかがポリシーによって判断されます。

たとえば、1, 000 件のリクエストを許可する 2 時間のウィンドウを定義します。過去 2 時間のウィンドウで割り当てカウントが計算されるので、新しいリクエストを午後 4 時 45 分に受信した場合、午後 2 時 45 分以降のリクエスト数が計算されます。この 2 時間のウィンドウで割り当て上限を超えていない場合、リクエストは許可されます。

1 分後の午後 4 時 46 分に別のリクエストを受信した場合、午後 2 時 46 分以降の割り当てカウントが計算され、上限の超過がないかどうか確認されます。

rollingwindow タイプの場合、カウンタはリセットされませんが、リクエストごとに再計算されます。

割り当てカウンタについて

API プロキシフローで Quota ポリシーが実行されると、割り当てカウンタが減少します。カウンタが上限に達すると、そのカウンタに関連付けられた API 呼び出しはそれ以上できなくなります。構成によっては、割り当てポリシーで 1 つ以上のカウンタを使用できます。複数のカウンタを使用する場合、どのように動作するのかを理解することが重要です。

API プロダクトの割り当てがカウントされる仕組み

API プロキシが API プロダクトに含まれている場合、そのプロダクトで定義されている割り当てルールを使用するように、Quota ポリシーを構成できます。API プロダクトでは、プロダクトレベルまたは個々のオペレーションのレベルで割り当てルールを指定できます。

API プロダクトで定義されたオペレーションごとに個別の割り当てカウンタが維持され、次のルールが適用されます。

オペレーションに割り当てが定義されている場合、そのオペレーションの割り当てルールは、プロダクトレベルで定義された割り当てルールよりも優先されます。オペレーションごとに個別の割り当てカウンタが作成されます。オペレーションのパスに対する API 呼び出しを行うと、カウンタが加算されます。
オペレーションに割り当てが定義されていない場合、プロダクトレベルの割り当てルールが適用されます。ただし、オペレーションでは個別の割り当てカウンタが維持されます。この場合、割り当てルールがプロダクトレベルで定義されても、オペレーションが自身のカウンタを維持する点は理解する必要があります。
API プロダクトに割り当ての定義が含まれない場合（プロダクトレベルでもオペレーションレベルでもない場合）、ポリシーで指定された割り当てルールが適用されます。ただし、この場合も、API プロダクトのオペレーションごとに個別の割り当てカウンタが維持されます。

以降のセクションでは、カウンタのオプションと動作について詳しく説明します。

API プロキシレベルのカウンタの構成

API プロキシスコープで割り当てカウントを維持するように API プロダクトを構成できます。この場合、API プロダクトレベルで指定された割り当て構成は、独自の割り当てが指定されていないすべてのオペレーションで共有されます。この構成の効果は、この API プロダクトの API プロキシレベルでグローバルカウンタを作成することです。

この構成を行うには、/apiproducts Apigee API を使ってプロダクトを作成または更新し、quotaCountScope属性を作成リクエストまたは更新リクエストで PROXY に設定します。PROXY 構成により、同じプロキシに関連付けられ、独自のカウンタを持たない、API プロダクトに定義されたすべてのオペレーションは、API プロダクトレベルで設定された同じ割り当てカウンタを共有することになります。

図 1 では、オペレーション 1 と 2 は Proxy1 に関連付けられており、オペレーション 4 と 5 は Proxy3 に関連付けられています。quotaCounterScope=PROXY が API プロダクトに設定されているため、これらの各オペレーションは API プロダクトレベルの割り当て設定を共有します。これらのオペレーションは同じ割り当て構成を共有しますが、プロキシの関連付けに基づいて個別のカウンタを使用します。一方、オペレーション 3 は独自の割り当て構成が設定されているため、quotaCounterScope フラグの影響を受けません。

図 1: quotaCounterScope フラグの使用

quotaCounterScope=PROXY の場合、割り当て構成が設定されているプロキシリソースと設定されていないプロキシリソースがあるオペレーションは構成しないことをおすすめします。たとえば、図 1 で、オペレーション 4 に独自の割り当て構成があり、オペレーション 5 に割り当てがない場合、その構成はアンチパターンと見なされます。

デフォルトでは、オペレーションに割り当てが定義されていない場合、プロダクトレベルの割り当てルールが適用されます。ただし、オペレーションでは個別の割り当てカウンタが維持されます。

使用中の API プロダクトがない場合の割り当てのカウント方法

API プロキシに関連付けられた API プロダクトがない場合、Quota ポリシーは、API プロキシ内での参照回数に関係なく、1 つのカウンタを保持します。割り当てカウンタの名前は、ポリシーの name 属性に基づいています。

たとえば、MyQuotaPolicy という名前の Quota ポリシーを作成し、リクエストを 5 つに制限して、API プロキシで複数のフロー（フロー A、B、C）に配置します。複数のフローで使用されていても、維持されるカウンタは 1 つだけです。このカウンタは、ポリシーのすべてのインスタンスで更新されます。

フロー A が実行される -> MyQuotaPolicy が実行され、カウンタが 1 に設定される
フロー B が実行される -> MyQuotaPolicy が実行され、カウンタが 2 に設定される
フロー A が実行される -> MyQuotaPolicy が実行され、カウンタが 3 に設定される
フロー C が実行される -> MyQuotaPolicy が実行され、カウンタが 4 に設定される
フロー A が実行される -> MyQuotaPolicy が実行され、カウンタが 5 に設定される

割り当てカウンタが上限に達したため、この 3 つのフローのいずれかに対する次のリクエストは拒否されます。

API プロキシフローの複数の場所で同じ Quota ポリシーを使用すると、意図せずに予想よりも早く割り当てを使い切る場合があります。これは、アンチパターンの概要で説明されているアンチパターンです。

このようにするのではなく、API プロキシで複数の Quota ポリシーを定義して、フローごとに異なるポリシーを使用することもできます。各 Quota ポリシーは、ポリシーの name 属性に基づいて独自のカウンタを維持します。

ポリシー構成で複数のカウンタを作成する

Quota ポリシーで <Class> 要素または <Identifier> 要素を使用すると、1 つのポリシーで複数の一意のカウンタを定義できます。これらの要素を使用すると、リクエストを行ったアプリ、リクエストを行ったアプリデベロッパー、クライアント ID などのクライアント識別子に基づいて、1 つのポリシー内で異なるカウンタを維持できます。<Class> 要素や <Identifier> 要素の使用方法については、前述の例をご覧ください。

時間の表記

すべての割り当ての時間は、協定世界時（UTC）タイムゾーンに設定されます。

割り当ての時間表記は、国際標準 ISO 8601 で定義されている国際標準の日付表記に準拠しています。

日付は、年、月、日で定義され、YYYY-MM-DD の形式で記述します。たとえば、2021-02-04 は、2021 年 2 月 4 日を表します。

時刻は、hours:minutes:seconds の形式で時間、分、秒で定義されます。たとえば、23:59:59 は深夜 0 時の 1 秒前を表します。

1 つの日付に関連付けられる可能性のある 2 つの深夜を区別するために、00:00:00 と 24:00:00 という 2 つの表記を使用できます。したがって、2021-02-04 24:00:00 は 2021-02-05 00:00:00 と同じ日時になります。後者のほうがよく利用されています。

API プロダクトの構成からの割り当て設定の取得

API プロダクトの構成から割り当て上限を設定できます。この場合、制限は自動的に適用されません。代わりに、Quota ポリシーでプロダクトの割り当て設定を参照します。次に、Quota ポリシーが参照する割り当てをプロダクトに設定する利点をいくつか示します。

Quota ポリシーでは、API プロダクトのすべての API プロキシで統一された設定を使用できます。
API プロダクトの割り当て設定は実行時に変更でき、その値を参照する Quota ポリシーには、更新された割り当て値が自動的に設定されます。

API プロダクトの割り当て設定の使用について詳しくは、上記の「動的割り当て」の例をご覧ください。

割り当て上限のある API プロダクトの構成については、API プロダクトを管理するをご覧ください。

共有割り当てカウンタの構成

通常、割り当てポリシーでは、API プロキシに送信されたすべてのリクエストがカウントされます。ユースケースによっては、受信したリクエストの割り当てカウントを適用すると同時に、指定された条件を満たすターゲットレスポンスの割り当てカウントを増分する場合があります。3 つの割り当てポリシー要素 <SharedName>、<CountOnly>、<EnforceOnly> を同時に使用すると、割り当てポリシーをカスタマイズして、受信リクエストの割り当てを強制し、条件を指定できます。

たとえば、バックエンドターゲットからのレスポンスに 200 HTTP ステータスコードが含まれている API プロキシの割り当てカウンタを増分するとします。この特別なカウントを行うには、次のようにします。

<SharedName> 要素を名前の値に設定し、<EnforceOnly> 要素を true に設定して、ProxyEndpoint リクエストフローに Quota ポリシーを追加します。
ProxyEndpoint レスポンスフローに別の Quota ポリシーを追加します。<SharedName> 要素は最初のポリシーと同じ名前の値に設定し、<CountOnly> 要素は true に設定します。
2 番目の Quota ポリシー（<CountOnly> を含む）を、割り当てカウンタを増分する条件を設定する条件付きステップに配置します。

共有カウンタの使用方法を示す例については、サンプルセクションの共有カウンタをご覧ください。

サンプル

割り当て期間を開始または終了するポリシーコードのサンプルを紹介します。

その他の動的割り当て

<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 ポリシーで Quota ポリシーに渡される情報に基づいてさまざまな割り当て設定を適用するように構成できます。このような割り当て設定はサービスプランとも呼ばれます。動的割り当てでは、アプリのサービスプランを確認して、その設定を適用します。

たとえば、API プロダクトを作成するときに、必要に応じて、割り当て上限、時間単位、間隔を設定できます。ただし、これらの値を API プロダクトに設定しただけでは、API プロキシで使用されません。これらの値を読み取る API プロキシに Quota ポリシーを追加する必要があります。詳しくは、API プロダクトを作成するをご覧ください。

上記の例では、Quota ポリシーを含む API プロキシは、verify-api-key という名前の VerifyAPIKey ポリシーを使用して、リクエストで渡された API キーを検証します。次に、Quota ポリシーは、VerifyAPIKey ポリシーのフロー変数にアクセスして、API プロダクトに設定された割り当て値を読み取ります。

別の方法としては、個々のデベロッパーまたはアプリに対してカスタム属性を設定し、それらの値を Quota ポリシーで読み取ることです。たとえば、デベロッパーごとに異なる割り当て値を設定するには、上限、時間単位、間隔を含むカスタム属性をデベロッパーごとに設定します。次に、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>

この例では、VerifyAPIKey フロー変数を使用して、デベロッパーに設定されたカスタム属性を参照しています。

Quota ポリシーのパラメータを設定する場合は、任意の変数を使用できます。これらの変数は次のものから取得できます。

フロー変数
API プロダクト、アプリまたはデベロッパーのプロパティ
Key-Value マップ（KVM）
ヘッダー、クエリパラメータ、フォームパラメータなど

各 API プロキシについて、他のすべてのプロキシの他のすべての Quota ポリシーと同じ変数を参照する Quota ポリシーを追加することも、Quota ポリシーでそのポリシーとプロキシに固有の変数を参照することもできます。

開始日時

<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 です。calendar タイプのポリシーに <StartTime> 値を指定しない場合、Apigee によってエラーが発行されます。

各アプリの割り当てカウンタは、<StartTime>、<Interval>、<TimeUnit> の値に基づいて更新されます。この例では、Quota で 2021 年 2 月 18 日午前 10 時 30 分（GMT）にカウントを開始し、5 時間ごとに更新されます。したがって、次の更新は 2021 年 2 月 18 日午後 3 時 30 分（GMT）に行われます。

アクセスカウンタ

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

API プロキシは、Quota ポリシーが設定したフロー変数にアクセスします。API プロキシでこれらのフロー変数にアクセスすると、条件付きの処理や、割り当て上限に近いポリシーのモニタリングを行うことができます。また、現在の割り当てカウンタをアプリに返すこともできます。

ポリシーのフロー変数へのアクセスはポリシーの name 属性に基づいているため、上記の <Quota> というポリシーの場合、次の形式でフロー変数にアクセスします。

ratelimit.QuotaPolicy.allowed.count: 許可された数。
ratelimit.QuotaPolicy.used.count: 現在のカウンタ値。
ratelimit.QuotaPolicy.expiry.time: カウンタがリセットされる UTC 時間。

以下で説明するように、この他にもアクセスできるフロー変数が多数あります。

たとえば、次の AssignMessage ポリシーを使用すると、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>

共有カウンタ

次の例は、API プロキシの共有カウンタを構成する方法を示しています。ここでは、ターゲットレスポンスが HTTP ステータス 200 の場合に、割り当てカウンタも増分されます。両方の割り当てポリシーで同じ <SharedName> 値が使用されるため、両方の割り当てポリシーが同じ割り当てカウンタを共有します。詳細については、共有割り当てカウンタの構成をご覧ください。

ProxyEndpoint 構成の例:

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

最初の Quota ポリシーの例:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

2 番目の Quota ポリシーの例:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

最初のリクエスト

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

このサンプルコードを使用して、「1 時間あたり 10,000 件の呼び出し」という割り当てを適用します。このポリシーでは、1 時間ごとに割り当てカウンタをリセットします。1 時間が経過する前にカウンタが 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 プロキシの複数の場所で参照できます。たとえば、プロキシの PreFlow に配置すると、リクエストを受信するたびに実行されます。また、API プロキシの複数のフローに配置することもできます。このポリシーをプロキシの複数の場所で使用すると、ポリシーのすべてのインスタンスで更新される単一のカウンタが維持されます。

また、API プロキシで複数の割り当てポリシーを定義することもできます。各 Quota ポリシーは、ポリシーの 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>

デフォルトでは、Quota ポリシーは、リクエストの送信元に関係なく、API プロキシのカウンタを 1 つ定義します。また、Quota ポリシーで <Identifier> 属性を使用して、<Identifier> 属性の値に基づいて個別のカウンタを維持することもできます。

たとえば、クライアント ID ごとに個別のカウンタを定義するには、<Identifier> タグを使用します。プロキシへのリクエストでは、クライアントアプリは上記の例のように clientID を含むヘッダーを渡します。

<Identifier> 属性には任意のフロー変数を指定できます。たとえば、id という名前のクエリパラメータに一意の識別子が含まれるように指定できます。

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

VerifyAPIKey ポリシーを使用して API キーを検証するか、または OAuth トークンで OAuthV2 ポリシーを使用する場合、API キーまたはトークンの情報を使用して、同じ Quota ポリシーに対して個々のカウンタを定義できます。たとえば、次の <Identifier> 要素では、verify-api-key という名前の VerifyAPIKey ポリシーの client_id フロー変数を使用しています。

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

一意の各 client_id 値により、Quota ポリシーで独自のカウンタを定義できるようになりました。

クラス

<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> の属性と子要素です。一部の要素の組み合わせは相互に排他的か、必須ではありません。具体的な使用方法については、サンプルをご覧ください。

下の verifyapikey.my-verify-key-policy.apiproduct.* 変数は、リクエスト内でアプリの API キーを確認するために、my-verify-key-policy という VerifyAPIKey ポリシーを使用する際に、デフォルトで使用できます。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

属性	説明	デフォルト	要否
type	Quota ポリシータイプを設定します。これにより、割り当てカウンタで割り当て使用量を確認するタイミングと方法、リセット方法が決まります。 `type` を設定しない場合、カウンタは、分、時間、日、週、月の始まりに開始します。有効な値は次のとおりです。 `calendar` `rollingwindow` `flexi` 各タイプの詳細については、Quota ポリシーのタイプをご覧ください。	なし	省略可

Quota ポリシータイプを設定します。これにより、割り当てカウンタで割り当て使用量を確認するタイミングと方法、リセット方法が決まります。

type を設定しない場合、カウンタは、分、時間、日、週、月の始まりに開始します。

有効な値は次のとおりです。

calendar
rollingwindow
flexi

各タイプの詳細については、Quota ポリシーのタイプをご覧ください。

なし

省略可

次の表に、すべてのポリシーの親要素に共通する属性を示します。

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

`<Allow>`

割り当てカウントの上限を指定します。ポリシーのカウンタがこの上限の値に達すると、カウンタをリセットするまで後続の呼び出しは拒否されます。

フロー変数に基づいて <Allow> 要素に条件付けする <Class> 要素を含めることもできます。

デフォルト値	なし
必須かどうか	省略可
型	整数型または複合型
親要素	`<Quota>`
子要素	`<Class>`

<Allow> 要素を設定するには、次の 3 つの方法があります。

<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

属性	説明	デフォルト	要否
count	割り当てのメッセージ数を指定します。たとえば、`count` 属性値が 100、`Interval` が 1、`TimeUnit` が月の場合、1 か月あたり 100 個のメッセージの割り当てが指定されます。	2000	省略可
countRef	割り当てのメッセージカウントを含むフロー変数を指定します。`countRef` は `count` 属性よりも優先されます。	none	省略可

割り当てのメッセージ数を指定します。

たとえば、count 属性値が 100、Interval が 1、TimeUnit が月の場合、1 か月あたり 100 個のメッセージの割り当てが指定されます。

2000

省略可

countRef

割り当てのメッセージカウントを含むフロー変数を指定します。countRef は count 属性よりも優先されます。

none

省略可

`<Class>`

フロー変数の値に基づいて、<Allow> 要素の値に条件付けできます。<Class> の異なる <Allow> 子タグごとに、ポリシーによって異なるカウンタが維持されます。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<Allow>`
子要素	`<Allow>`（`<Class>` の子）

<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 の値にすることができます。クエリパラメータに無効な値が含まれている場合、ポリシーは割り当て違反エラーを返します。

注: 同じ Quota ポリシーで <Class> 要素と <Identifier> 要素の両方を使用することはできません。

次の表は、<Class> の属性を示したものです。

属性	説明	デフォルト	プレゼンス
ref	割り当ての割り当てクラスを含むフロー変数を指定します。	none	必須

`<Allow>`（`<Class>` の子）

<Class> 要素で定義された割り当てカウンタの上限を指定します。<Class> の各 <Allow> 子タグによって、ポリシーで複数のカウンタを維持します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<Class>`
子要素	なし

例:

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

この例では、Quota ポリシーで、peak_time と off_peak_time という名前の 2 つの割り当てカウンタを維持します。どちらを使用するかは、<Class> の例に示すように、渡されたクエリパラメータによって異なります。

次の表は、<Allow> の属性を示したものです。

属性	説明	デフォルト	要否
class	割り当てカウンタの名前を定義します。	none	必須
count	カウンタの割り当て制限を指定します。	none	必須

`<Interval>`

割り当てが計算される期間を指定します。

デフォルト値	なし
必須かどうか	必須
型	整数
親要素	`<Quota>`
子要素	なし

整数（1、2、5、60 など）を、指定した <TimeUnit> 要素（分、時間、日、週、月）と組み合わせて指定し、Apigee で割り当ての使用量を計算する期間を決定します。

たとえば、間隔が 24 で <TimeUnit> が hour の場合、割り当ては 24 時間にわたって計算されます。

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

次の表は、<Interval> の属性を示したものです。

属性	説明	デフォルト	プレゼンス
ref	割り当ての間隔を含むフロー変数を指定します。`ref` は明示的な間隔の値よりも優先されます。参照と値の両方を指定すると、参照が優先されます。ランタイム時に `ref` が解決されない場合は、の値が使用されます。	none	省略可

`<TimeUnit>`

割り当てに適用される時間の単位を指定します。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	`<Quota>`
子要素	なし

minute、hour、day、week、month、year から選択します。

注: このポリシーでは、時間単位として second もサポートされます。ただし、second は、非分散カウンタに対してのみサポートされます（<Distributed> が false に設定されている場合）。ここで second 値を使用する代わりに、秒レベルでリクエストトラフィックの急増を制限するために、SpikeArrest ポリシーを使用することをおすすめします。

たとえば、Interval が 24 で TimeUnit が hour の場合、割り当ては 24 時間にわたって計算されます。

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

デフォルト:	none
要否:	必須
型:	文字列

次の表は、<TimeUnit> の属性を示したものです。

属性	説明	デフォルト	プレゼンス
ref	割り当ての時間単位を含むフロー変数を指定します。`ref` は明示的な間隔の値よりも優先されます。ランタイムに `ref` が解決されない場合、間隔値が使用されます。	none	省略可

`<StartTime>`

type が calendar に設定されている場合に、割り当てカウンタのカウントを開始する日時を指定します。アプリからリクエストを受信しているかどうかは関係ありません。

デフォルト値	なし
必須かどうか	省略可（`type` が `calendar` に設定されている場合は必須）
型	ISO 8601 の日時形式の文字列。
親要素	`<Quota>`
子要素	なし

type が calendar に設定されており、フロー変数への参照を使用できない場合、明示的な <StartTime> を指定する必要があります。type 値が設定されていない場合に <StartTime> 値を指定すると、Apigee はエラーを返します。

例:

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

`<Distributed>`

Apigee がリクエストの処理に 1 つのノードを使用するか、それ以上のノードを使用するかを決定します。

デフォルト値	false
必須かどうか	省略可
型	ブール値
親要素	`<Quota>`
子要素	なし

ポリシーが中央カウンタを維持し、すべてのノードで継続的にカウンタを同期するように指定するには、true に設定します。ノードはアベイラビリティゾーンやリージョンにわたって存在できます。

デフォルト値である false を使用する場合、各ノードの数が共有されないため、割り当てを超過する可能性があります。

<Distributed>false</Distributed>

カウンタが同期され、リクエストごとに更新されることを保証するには、<Distributed> と <Synchronous> を true に設定します。

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

`<Synchronous>`

分散割り当てカウンタを同時に更新するかどうかを決定します。

デフォルト値	false
必須かどうか	省略可
型	ブール値
親要素	`<Quota>`
子要素	なし

分散割り当てカウンタを同時に更新するには、true に設定します。つまり、API に対するリクエストで割り当てが確認されるのと同時に、カウンタの更新が行われます。割り当てを超える API 呼び出しを許可しないことが重要な場合は、true に設定します。

注: カウンタに同期的更新を実装すると、パフォーマンスに影響し、スループットが低下する可能性があります。<Synchronous> を使用すると、割り当てポリシーで一部のトランザクションを処理できなくなる場合があります。

割り当てカウンタを非同期で更新するには、false に設定します。この場合、中央のリポジトリにある割り当てカウンタが非同期で更新されるため、一部の API 呼び出しで割り当てを超過する可能性があります。ただし、同期更新にみられるパフォーマンスの低下が起きることはありません。

非同期更新のデフォルトの間隔は 10 秒です。この非同期動作は、<AsynchronousConfiguration> 要素を使用して構成します。

<Synchronous>false</Synchronous>

`<AsynchronousConfiguration>`

ポリシー構成要素 <Synchronous> が存在しないか、存在しているものの、false に設定されている場合、分散割り当てカウンタの同期間隔を構成します。<Synchronous> が true に設定されている場合、Apigee によってこの要素が無視されます。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<Quota>`
子要素	`<SyncIntervalInSeconds>` `<SyncMessageCount>`

<SyncIntervalInSeconds> 子要素または <SyncMessageCount> 子要素を使用して、期間またはメッセージカウントの後に同期できます。これらを同時に設定することはできません。たとえば、

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

または

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

`<SyncIntervalInSeconds>`

10 秒経過した後に非同期更新を行うデフォルトの動作をオーバーライドします。

デフォルト値	10 秒
必須かどうか	省略可
種類	整数
親要素	`<AsynchronousConfiguration>`
子要素	なし

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

同期間隔は、上限で説明しているように 10 秒以上にする必要があります。

`<SyncMessageCount>`

割り当ての更新間のすべてのノードにわたるリクエスト数を指定します。

デフォルト値	なし
必須かどうか	省略可
種類	整数
親要素	`<AsynchronousConfiguration>`
子要素	なし

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

この例では、各ノードにわたって、割り当て数が 5 つのリクエストごと更新されることを指定しています。

`<Identifier>`

フロー変数に基づいて一意のカウンタが作成されるようにポリシーを構成します。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<Quota>`
子要素	なし

ID 要素を使用すると、フロー変数の値で定義された複数のバケットに呼び出し数を割り当てることができます。たとえば、VerifyAPIKey ポリシーの後に入力される developer.id 変数を使用して、特定のデベロッパーによって作成されたすべてのアプリのインスタンスに対して 1 つの割り当て上限を適用できます。また、client_id を使用して、特定のアプリごとに割り当て制限を適用することもできます。後者の構成は次のようになります。

<Identifier ref="client_id"/>

AssignMessage ポリシーや JavaScript ポリシーで設定するカスタム変数、または VerifyAPIKey ポリシーや VerifyJWT ポリシーで設定されるような、暗黙的に設定される変数のいずれかを参照できます。変数の詳細については、フロー変数の使用をご覧ください。Apigee によって定義されるよく知られた変数のリストについては、フロー変数のリファレンスをご覧ください。

この要素を使用しない場合、ポリシーはすべての呼び出し数を特定の Quota ポリシーの 1 つのカウンタに割り当てます。

この要素については、ID を指定しない場合の Quota ポリシーの仕組みでも説明されています。

次の表に、<Identifier> の属性を示します。

属性説明デフォルトプレゼンス

ref

属性	説明	デフォルト	プレゼンス
ref	リクエストに使用するカウンタを特定するフロー変数を指定します。この変数は、HTTP ヘッダー、クエリパラメータ、フォームパラメータ、メッセージコンテンツの要素、あるいは呼び出し回数の割り当て方法を特定する他の値を参照できます。 `client_id` は、変数としてよく使用されています。`client_id` は、API キーまたはコンシューマキーとも呼ばれ、アプリが Apigee の組織に登録されるときに生成されます。API で API キーまたは OAuth 認可ポリシーが有効になっている場合、この ID を使用できます。	なし	省略可

リクエストに使用するカウンタを特定するフロー変数を指定します。この変数は、HTTP ヘッダー、クエリパラメータ、フォームパラメータ、メッセージコンテンツの要素、あるいは呼び出し回数の割り当て方法を特定する他の値を参照できます。

client_id は、変数としてよく使用されています。client_id は、API キーまたはコンシューマキーとも呼ばれ、アプリが Apigee の組織に登録されるときに生成されます。API で API キーまたは OAuth 認可ポリシーが有効になっている場合、この ID を使用できます。

なし

省略可

`<MessageWeight>`

割り当てを目的とした各メッセージに適用される費用を指定します。この要素を使用すると、リクエストメッセージへの影響が大きくなります。たとえば、他のリソースよりも使用するコンピューティングリソースが多くなる場合があります。

デフォルト値	なし
必須かどうか	省略可
種類	整数
親要素	`<Quota>`
子要素	なし

たとえば、POST のメッセージを GET メッセージの 2 倍コストがかかるとみなしたいとします。その場合、<MessageWeight> を POST に対しては 2 に設定し、GET に対しては 1 を設定します。リクエストによってカウンタが影響を受けないように、<MessageWeight> を 0 に設定することもできます。

この例では、割り当てが 1 分あたり 10 件のメッセージで、POST リクエストの <MessageWeight> が 2 の場合、割り当てによって 10 分間に 5 件の POST リクエストが許可されます。カウンタがリセットされる前の追加の POST リクエストまたは GET リクエストは拒否されます。

<MessageWeight> を表す値はフロー変数で指定する必要があり、HTTP ヘッダー、クエリパラメータ、XML または JSON リクエストのペイロード、その他のフロー変数から抽出できます。たとえば、weight という名前のヘッダーで設定します。

<MessageWeight ref="message_weight"/>

`<UseQuotaConfigInAPIProduct>`

時間単位、間隔、許容される最大値など、API プロダクトの割り当て設定を定義します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<Quota>`
子要素	`<DefaultConfig>`

Quota ポリシーに <UseQuotaConfigInAPIProduct> 要素を追加すると、<Quota> の <Allow>、<Interval>、<TimeUnit> の子要素は Apigee によって無視されます。

次の例に示すように、<UseQuotaConfigInAPIProduct> 要素は、デフォルト設定の単純な入れ物で、<DefaultConfig> 要素を使用して定義します。

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

stepName 属性を使用して、フロー内で OAuthv2 ポリシーの VerifyAPIKey ポリシーオペレーションまたは ValidateToken ポリシーオペレーションを参照できます。

次の表に、<UseQuotaConfigInAPIProduct> の属性を示します。

属性	説明	デフォルト	要否
stepName	フロー内の認証ポリシーの名前を識別します。対象は、VerifyAPIKey ポリシーまたは OAuthv2 ポリシーのいずれかです。	なし	必須

詳しくは以下をご覧ください。

`<DefaultConfig>`

API プロダクトの割り当てのデフォルト値が含まれます。<DefaultConfig> を定義する場合は、3 つの子要素がすべて必要です。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<UseQuotaConfigInAPIProduct>`
子要素	`<Allow>` `<Interval>` `<TimeUnit>`

これらの値は、API プロダクトのオペレーション（UI または API プロダクト API のいずれか）と Quota ポリシーの両方で定義できます。ただし、このように設定した場合、API プロダクトの設定が優先され、Quota ポリシーの設定は無視されます。

この要素の構文は次のとおりです。

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

この割り当てポリシーを共有と識別します。同じ <SharedName> 値を持つ API プロキシのすべての割り当てポリシーは、同じ基盤となる割り当てカウンタを共有します。この要素が存在する場合、<EnforceOnly> 要素または <CountOnly> 要素も存在する必要があります。

詳細および例については、共有割り当てカウンタの構成を参照してください。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<Quota>`
子要素	なし

`<CountOnly>`

ProxyEndpoint レスポンスフローの条件付きステップでこの要素を true に設定した割り当てポリシーを配置し、基盤となる割り当てカウンタを条件付きで増やします。この要素が存在する場合、<SharedName> 要素と <EnforceOnly> 要素も存在する必要があります。

詳細および例については、共有割り当てカウンタの構成を参照してください。

デフォルト値	false
必須かどうか	省略可
型	ブール値
親要素	`<Quota>`
子要素	なし

`<EnforceOnly>`

この要素を true に設定した Quota ポリシーを API プロキシのリクエストフローに配置します。この構成により、同じ <SharedName> 値を持つ API プロキシの Quota ポリシーで、割り当て数を共有できます。この要素が存在する場合、<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 時間（ミリ秒）を返します。この時間が経過すると、割り当てが期限切れになり、新しい割り当て期間が開始されます。 Quota ポリシーのタイプが `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 プロキシのデプロイが失敗します。
`InvalidQuotaTimeUnit`	`<TimeUnit>` 要素で指定された時間単位がサポートされていない場合、API プロキシのデプロイが失敗します。サポートされている時間単位は `minute`、`hour`、`day`、`week`、`month` です。
`InvalidQuotaType`	`<Quota>` 要素の `type` 属性で指定された割り当てのタイプが無効な場合、API プロキシのデプロイが失敗します。サポートされている割り当てのタイプは、`default`、`calendar`、`flexi`、`rollingwindow` です。
`InvalidStartTime`	`<StartTime>` 要素で指定された時間の形式が無効な場合、API プロキシのデプロイが失敗します。有効な形式は `yyyy-MM-dd HH:mm:ss` です。これは ISO 8601 の日付と時刻の形式です。たとえば、`<StartTime>` 要素で指定された時間が `7-16-2017 12:00:00` の場合、API プロキシのデプロイが失敗します。
`StartTimeNotSupported`	割り当てのタイプが `calendar` 以外の `<StartTime>` 要素が指定されている場合、API プロキシのデプロイが失敗します。`<StartTime>` 要素は、`calendar` 割り当てタイプでのみサポートされています。たとえば、`<Quota>` 要素の `type` 属性が `flexi` または `rolling window` に設定されている場合、API プロキシのデプロイが失敗します。
`InvalidTimeUnitForDistributedQuota`	`<Distributed>` 要素が `true` に設定され、`<TimeUnit>` 要素が `second` に設定されている場合、API プロキシのデプロイが失敗します。分散割り当てで時間単位 `second` は無効です。
`InvalidSynchronizeIntervalForAsyncConfiguration`	`Quota` ポリシーの `<AsynchronousConfiguration>` 要素内の `<SyncIntervalInSeconds>` 要素に指定された値が 0 未満の場合、API プロキシのデプロイが失敗します。
`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`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

注: 現在、Quota ポリシーでレート制限を適用すると、ステータスコード 500 が返されます。Apigee マネージドサービスを使用していて、Quota ポリシーが 429 を返すようにする場合は、Apigee サポートに連絡して、features.isHTTPStatusTooManyRequestEnabled プロパティの有効化を依頼してください。詳細については、Quota ポリシー違反のデフォルトステータスコードとしての Http 429 をご覧ください。

注意: プロパティを更新するときは、既存のプロパティが変更されていない場合でも、すべて API に渡す必要があります。ペイロードでプロパティを省略すると、プロパティが削除されます。

curl -u email:password -X POST -H "Content-type:application/xml" \
  http://LOAD_BALANCER_IP:8080/v1/o/myorg \
  -d '<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Environments/>
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
    </Properties>
  </Organization>'

Quota ポリシー

概要

動画

はじめに

動的割り当て

分散と同期

メッセージ ウェイト

カレンダー

ローリング ウィンドウ

Flexi

条件付き割り当て

フロー変数

エラー処理

Quota ポリシーのタイプ

割り当てカウンタについて

API プロダクトの割り当てがカウントされる仕組み

API プロキシレベルのカウンタの構成

使用中の API プロダクトがない場合の割り当てのカウント方法

ポリシー構成で複数のカウンタを作成する

時間の表記

API プロダクトの構成からの割り当て設定の取得

共有割り当てカウンタの構成

サンプル

その他の動的割り当て

開始日時

アクセス カウンタ

共有カウンタ

最初のリクエスト

ID を設定する

クラス

<Quota> 要素

<DisplayName> 要素

<Allow>

<Class>

<Allow>（<Class> の子）

<Interval>

<TimeUnit>

<StartTime>

<Distributed>

<Synchronous>

<AsynchronousConfiguration>

<SyncIntervalInSeconds>

<SyncMessageCount>

<Identifier>

<MessageWeight>

<UseQuotaConfigInAPIProduct>

<DefaultConfig>

<SharedName>

<CountOnly>

<EnforceOnly>

フロー変数

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

スキーマ

関連トピック

メッセージウェイト

ローリングウィンドウ

アクセスカウンタ

`<Quota>` 要素

`<Allow>`

`<Class>`

`<Allow>`（`<Class>` の子）

`<Interval>`

`<TimeUnit>`

`<StartTime>`

`<Distributed>`

`<Synchronous>`

`<AsynchronousConfiguration>`

`<SyncIntervalInSeconds>`

`<SyncMessageCount>`

`<Identifier>`

`<MessageWeight>`

`<UseQuotaConfigInAPIProduct>`

`<DefaultConfig>`

`<SharedName>`

`<CountOnly>`

`<EnforceOnly>`

エラーリファレンス

ランタイムエラー

エラーレスポンスの例