割り当てポリシー

このページの内容は 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 ポリシーで割り当てを管理する方法を説明しています。

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> の値に基づいてリセットする割り当てを構成します。

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

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 フラグの使用

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

使用中の 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 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>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 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>

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

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

以下の属性は、このポリシーに固有のものです。

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

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

<Allow>

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

フロー変数に基づいて <Allow> 要素に条件付けする <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> の属性を示したものです。

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

この例では、Quota ポリシーで、peak_time と off_peak_time という名前の 2 つの割り当てカウンタを維持します。どちらを使用するかは、<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 に設定されている場合に、割り当てカウンタのカウントを開始する日時を指定します。アプリからリクエストを受信しているかどうかは関係ありません。

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

例:

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

<Distributed>

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

ポリシーが中央カウンタを維持し、すべてのノードで継続的にカウンタを同期するように指定するには、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 要素を使用すると、フロー変数の値で定義された複数のバケットに呼び出し数を割り当てることができます。たとえば、VerifyAPIKey ポリシーの後に入力される developer.id 変数を使用して、特定のデベロッパーごとによって作成されたすべてのアプリのすべてのインスタンスに対して 1 つの割り当て上限を適用できます。また、client_id を使用して、特定のアプリごとに割り当て制限を適用することもできます。後者の構成は次のようになります。

<Identifier ref="client_id"/>

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

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

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

次の表は、<Identifier> の属性をまとめたものです。

<MessageWeight>

割り当てを目的として各メッセージに割り当てる費用を指定します。この要素を使用すると、リクエスト メッセージの影響を増加させます。たとえば、他のリソースよりも使用するコンピューティング リソースを増やすことができます。

たとえば、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 プロダクトの割り当て設定を定義します。

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

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

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

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

次の表は、<UseQuotaConfigInAPIProduct> の属性をまとめたものです。

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

• <DefaultConfig>
• API プロダクトとは
• API プロダクトの管理

<DefaultConfig>

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

これらの値は、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>

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

• API プロダクトとは
• API プロダクトの管理

<SharedName>

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

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

<CountOnly>

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

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

<EnforceOnly>

この要素を true に設定した Quota ポリシーを API プロキシのリクエスト フローに配置します。この構成により、同じ <SharedName> 値を持つ API プロキシの Quota ポリシーで、割り当て数を共有できます。この要素が存在する場合、<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 ポリシー

Quota ポリシーと Spike Arrest ポリシーの比較