割り当てポリシー

概要

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

• API プロキシを含むプロダクト
• API をリクエストするアプリ
• アプリのデベロッパー
• その他の条件

全体のトラフィックの急増から保護する目的で Quota ポリシーを使用しないでください。この目的には Spike Arrest ポリシーを使用します。Spike Arrest ポリシーをご覧ください。

動画

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

サンプル

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

<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>2017-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 async="false" 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>

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

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2017-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 ポリシーについて

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

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

SpikeArrest という割り当てのバリエーションを使用すると、突然の使用量の増加、バグの多いクライアント、悪意のある攻撃によるトラフィックの急増を防ぐことができます。SpikeArrest の詳細については、Spike Arrest ポリシーをご覧ください。

割り当ては個々の API プロキシに適用されます。複数の API プロキシ間で分散されることはありません。たとえば、API プロダクトに 3 つの API プロキシがある場合、この 3 つのプロキシが同じ割り当てポリシー構成を使用していても、この 3 つで 1 つの割り当てが共有されることはありません。

Quota ポリシーのタイプ

Quota ポリシーは、default、calendar、flexi、rollingwindow というさまざまなタイプのポリシーをサポートしています。次の表に示すように、ポリシーのタイプによって割り当てカウンタの開始時間とリセット条件が異なります。

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

この表には、rollingwindow タイプの値は記載されていません。Rolling window タイプを使用するには、割り当てサイズのウィンドウ（1 時間、1 日など）を設定します。新しいリクエストを受信すると、過去のウィンドウ時間に割り当てを超過していないかどうか確認されます。

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

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

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

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

デフォルトでは、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 ポリシーを使用すると、割り当てが予想より早く使い果たされてしまう可能性があり、これはアンチパターンと呼ばれます。これについては、Apigee Edge Antipatterns に関する書籍をご覧ください。

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

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

時間の表記

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

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

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

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

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

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

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

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

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

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

要素リファレンス

このポリシーで構成できる要素と属性は次のとおりです。一部の要素の組み合わせは相互に排他的か、必須ではありません。具体的な使用方法については、サンプルをご覧ください。verifyapikey.VerifyAPIKey.apiproduct.* 変数がデフォルトで使用できるのは、VerifyAPIKey という Verify API Key ポリシーを使用してリクエストに含まれるアプリの API キーを確認する場合です。API プロダクトの構成から割り当て設定を取得するで説明したように、変数の値は、キーが関連する API プロダクトの割り当て設定から取得されます。

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <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.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
</Quota>

<Quota> 属性

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

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

次の表は、すべてのポリシーの親要素に共通の属性を示したものです。

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使います。

<DisplayName>Policy Display Name</DisplayName>

<Allow> 要素

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

以下に、<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 の値が使用されます。

属性

<Allow> / <Class> 要素

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

<Class> 要素を使用するには、<Class> タグに ref 属性を使用してフロー変数を指定します。Edge は、フロー変数の値を使用して <Allow> 子タグのいずれかを選択し、ポリシーの許可数を決定します。Edge は、次に示すように、フロー変数の値を <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 の値にすることができます。クエリ パラメータに無効な値が含まれている場合、ポリシーは割り当て違反エラーを返します。

属性

<Allow> / <Class> / <Allow> 要素

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

例:

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

この例では、Quota ポリシーは peak_time と off_peak_time という 2 つの割り当てカウンタが維持されます。

属性

<Interval> 要素

整数（1、2、5、60 など）の指定に使用します。この整数は指定した TimeUnit（minute、hour、day、week、month）と組み合わせて、Edge が割り当ての使用量を計算する期間を決定します。

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

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

属性

<TimeUnit> 要素

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

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

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

属性

<StartTime> 要素

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

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

例:

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

<Distributed> 要素

Edge では、1 つ以上の Message Processor を使用してリクエストを処理できます。この要素を true に設定すると、ポリシーが中央のカウンタを維持し、すべての Message Processor で継続的に同期されるように指定されます。

デフォルト値の false を使用すると、各 Message Processor の数は共有されないため、割り当てを超過する可能性があります。

<Distributed>true</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 に設定されている場合に、分散割り当てカウンタ間の同期間隔を構成します。

SyncIntervalInSeconds または SyncMessageCount 子要素を使用して、一定の期間またはメッセージ数のいずれかを超過した後に同期できます。これらを同時に設定することはできません。例:

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

または

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

<AsynchronousConfiguration> / <SyncIntervalInSeconds> 要素

10 秒間隔で非同期更新を実行するデフォルトの動作をオーバーライドします。

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

同期間隔は、上限で説明されているとおり 10 秒以上にする必要があります。

<AsynchronousConfiguration> / <SyncMessageCount> 要素

割り当ての更新間隔ですべての Apigee Message Processor で発生するリクエスト数を指定します。

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

この例では、各 Apigee Edge Message Processor で割り当てカウントを 5 リクエストごとに更新します。

<Identifier> 要素

フロー変数に基づいて一意のカウンタが作成されるようにポリシーを構成するには、<Identifier> 要素を使用します。

この要素を使用しない場合、ポリシーは割り当てに適用された 1 つのカウンタを使用します。

この要素については、Apigee コミュニティの投稿 http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html にも説明があります。

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

属性

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

フロー変数

Quota ポリシーを実行すると、以下の事前定義のフロー変数が自動的に設定されます。フロー変数の詳細については、変数リファレンスをご覧ください。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Example fault rule

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

スキーマ

関連トピック

Reset Quota ポリシー

Spike Arrest ポリシー

Quota、Spike Arrest、Concurrent Rate Limit ポリシーの比較