割り当てポリシー

概要

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

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

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

動画

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

概要(新しい Edge)

概要(従来の Edge)

動的割り当て

分散と同期

メッセージ ウェイト

カレンダー

ローリング ウィンドウ

flexi

条件付き割り当て

フロー変数

エラー処理

サンプル

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

その他の動的割り当て

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

動的割り当てでは、ポリシーに渡される情報に応じて適用する割り当て設定を変えるように 1 つの Quota ポリシーを構成できます。この意味での割り当て設定は「サービスプラン」ともいいます。動的割り当ては、アプリの「サービスプラン」を確認してから設定を適用します。

: 要素の値とリファレンスの両方を指定すると、参照が優先されます。ランタイムに参照が解決されない場合、値が使用されます。

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

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

また、個々のデベロッパーまたはアプリにカスタム属性を設定して、これらの値を 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>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

typecalendar に設定された Quota の場合、明示的な <StartTime> 値を定義する必要があります。時間の値は、ローカル時間ではなく、GMT です。calendar タイプのポリシーに <StartTime> 値を指定しない場合、Edge はエラーを発行します。

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

アクセス カウンタ

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

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

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

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

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

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

このサンプルコードを使用して、「1 時間あたり 10,000 件の呼び出し」という割り当てを適用します。このポリシーは、1 時間ごとに割り当てカウンタをリセットします。1 時間以内にカウンタが 10,000 件の上限に達すると、10,000 件を超える呼び出しは拒否されます。

たとえば、カウンタが 2017-07-08 07:00:00 から始まる場合、2017-07-08 08:00:00(開始時刻から 1 時間)で 0 にリセットされます。最初のメッセージが 2017-07-08 07:35:28 で受信され、2017-07-08 08:00:00 より前にメッセージ数が 10,000 に達した場合、その数を超える呼び出しは正時にカウントがリセットされるまで拒否されます。

カウンタのリセット時間は、<Interval><TimeUnit> の組み合わせに基づきます。たとえば、<Interval> を 12、<TimeUnit> を hour に設定すると、カウンタは 12 時間ごとにリセットされます。<TimeUnit> は、minute、hour、day、week、または month に設定できます。

このポリシーは、API プロキシの複数の場所で参照できます。たとえば、プロキシの PreFlow に配置すると、リクエストを受信するたびに実行されます。また、API プロキシの複数のフローに配置することもできます。このポリシーをプロキシの複数の場所に配置すると、このポリシーのすべてのインスタンスが更新する 1 つのカウンタが維持されます。

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

ID の設定

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

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

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

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

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

VerifyAPIKey ポリシーを使用して API キーの検証を行う場合や、OAuthV2 ポリシーで OAuth トークンを使用する場合、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 ポリシーについて

割り当ては、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、calendarflexirollingwindow というさまざまなタイプのポリシーをサポートしています。次の表に示すように、ポリシーのタイプによって割り当てカウンタの開始時間とリセット条件が異なります。

時間単位 デフォルトまたは NULL のリセット calendar のリセット flexi のリセット
次の 1 分間の開始 <StartTime> から 1 分後 最初のリクエストの 1 分後
次の 1 時間の開始 <StartTime> から 1 時間後 最初のリクエストの 1 時間後
現在の日付の深夜(GMT) <StartTime> から 24 時間後 最初のリクエストの 24 時間後
週の終わりの日曜日の深夜(GMT) <StartTime> から 1 週間後 最初のリクエストの 1 週間後
月の最終日の深夜(GMT) <StartTime> から 1 か月後 最初のリクエストの 1 か月後

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:0024:00:00 という 2 つの表記を使用できます。したがって、2015-02-04 24:00:002015-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">

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

属性 説明 デフォルト 要否

割り当てカウンタが割り当て使用量を確認するタイミングと方法の判定に使用されます。詳細については、Quota ポリシーのタイプをご覧ください。

type 値を省略すると、アプリから最初のリクエスト メッセージを受信したときにカウンタを開始します。

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

  • calendar: 明示的な開始時間に基づいて割り当てを構成します。各アプリの割り当てカウンタは、設定した <StartTime><Interval><TimeUnit> の値に基づいて更新されます。
  • rollingwindow: 割り当て使用量の判定に「ローリング ウィンドウ」を使用する割り当てを構成します。rollingwindow の場合、ウィンドウのサイズは <Interval> 要素と <TimeUnit> 要素で判定され、たとえば 1 日となります。リクエストを受け取ると、Edge はリクエストの正確な時刻(たとえば午後 5:01)を調べ、前日の午後 5:01 からそのときまで(1 日)に受け取ったリクエストの数をカウントし、そのウィンドウ中に割り当てを超過したかどうかを判定します。
  • flexi: アプリから最初のリクエスト メッセージを受信したときにカウンタを開始し、<Interval>, <TimeUnit> の値に基づいてリセットするように割り当てを構成します。
カレンダー 省略可

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

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

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

要否: 省略可
型: 文字列

<Allow> 要素

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

以下に、<Allow> 要素を設定する 3 つの方法を示します。

<Allow count="2000"/>
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>

countcountRef の両方を指定すると、countRef が優先されます。countRef が実行時に解決されない場合は、count の値が使用されます。

デフォルト: なし
要否: 省略可
型: Integer

属性

属性 説明 デフォルト 要否
count

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

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

2000 省略可
countRef

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

なし 省略可

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

デフォルト: なし
要否: 省略可
型: なし

属性

属性 説明 デフォルト 要否
ref

割り当ての割り当てクラスを含むフロー変数を指定します。

なし 必須

<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_timeoff_peak_time という 2 つの割り当てカウンタが維持されます。

デフォルト: なし
要否: 省略可
型: なし

属性

属性 説明 デフォルト 要否
class

割り当てカウンタの名前を定義します。

なし 必須
count カウンタの割り当て制限を指定します。 なし 必須

<Interval> 要素

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

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

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
デフォルト: なし
要否: 必須
型: Integer

属性

属性 説明 デフォルト 要否
ref

割り当ての間隔を含むフロー変数を指定します。ref は明示的な間隔の値よりも優先されます。参照と値の両方を指定すると、参照が優先されます。ランタイムに ref が解決されない場合、値が使用されます。

なし 省略可

<TimeUnit> 要素

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

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

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
デフォルト: なし
要否: 必須
型:

文字列。minutehourdayweekmonth から選択します。

属性

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

<StartTime> 要素

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

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

例:

<StartTime>2017-7-16 12:00:00</StartTime>
デフォルト: なし
要否: typecalendar に設定されている場合は必須。
型:

ISO 8601 形式の日付と時刻の文字列。

<Distributed> 要素

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

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

<Distributed>true</Distributed>

カウンタが同期され、すべてのリクエストで更新されるようにするには、<Distributed><Synchronous> を true に設定します。

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
デフォルト: false
要否: 省略可
型: Boolean

<Synchronous> 要素

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

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

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

<Synchronous>false</Synchronous>
デフォルト: false
要否: 省略可
型: Boolean

<AsynchronousConfiguration> 要素

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

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

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

または

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
デフォルト: SyncIntervalInSeconds = 10 秒
要否: オプションです。<Synchronous>true に設定されている場合は無視されます。
型:

Compound

<AsynchronousConfiguration> / <SyncIntervalInSeconds> 要素

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

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

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

デフォルト: 10
要否: 省略可
型:

Integer

<AsynchronousConfiguration> / <SyncMessageCount> 要素

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

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

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

デフォルト: なし
要否: 省略可
型:

Integer

<Identifier> 要素

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

フロー変数で定義された特性の一意のカウンタを作成できます。たとえば、デベロッパーのメールアドレスを使用して、特定のデベロッパーに割り当てを関連付けます。カスタム変数を使用する場合も、Verify API Key ポリシーで使用できる事前定義された変数を使用する場合も、さまざまな変数を使用して割り当てを識別できます。変数リファレンスもご覧ください。

この要素を使用しない場合、ポリシーは割り当てに適用された 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"/>
デフォルト: なし
要否: 省略可
型:

文字列

属性

属性 説明 デフォルト 要否
ref

リクエストのカウンタを特定するフロー変数を指定します。ID は、HTTP ヘッダー、クエリ パラメータ、フォーム パラメータ、メッセージ コンテンツから入手できます。この ID は、それぞれのアプリ、アプリユーザー、アプリのデベロッパー、API プロダクトなどに固有のものです。

アプリを一意に識別するために最もよく使用される <Identifier>client_id です。client_id は、Apigee Edge で組織内で登録されたときにアプリに対して生成されるコンシューマ キーまたは API キーの別名です。API で API キーまたは OAuth 認可ポリシーが有効になっている場合、この ID を使用できます。

状況によっては、セキュリティ ポリシーが設定されていない場合など、client_id を使用できないときに割り当て設定を取得する必要があります。Access Entity ポリシーで該当する API プロダクトの設定を取得し、ExtractVariables で値を抽出します。抽出したコンテキスト変数を Quota ポリシーで使用します。詳細については、Access Entity ポリシーをご覧ください。

なし 省略可

<MessageWeight> 要素

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

たとえば、POST メッセージを GET メッセージよりも 2 倍の重みで計算するとします。したがって、MessageWeight は、POST の場合は 2、GET の場合は 1 に設定します。リクエストによってカウンタに影響が及ぼされないように、MessageWeight を 0 に設定することもできます。この例では、割り当てが 1 分あたり 10 個のメッセージで、POST リクエストの MessageWeight2 の場合、割り当ては 10 分間に 5 個の POST リクエストを許可します。カウンタがリセットされる前に発生した追加の POST または GET リクエストは拒否されます。

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

<MessageWeight ref="message_weight"/>
デフォルト: なし
要否: 省略可
型:

Integer

フロー変数

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 String 読み取り専用 ポリシーに追加された(クライアントの)ID 参照を返します。
ratelimit.{policy_name}.class String 読み取り専用 クラス 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 Boolean 読み取り専用

ポリシーが失敗したかどうかを表します(true または false)。

エラー リファレンス

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.

Fault code HTTP status Cause Fix
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Occurs if the <Interval> element is not defined within the Quota policy. This element is mandatory and used to specify the interval of time applicable to the quota. The time interval can be minutes, hours, days, weeks, or months as defined with the <TimeUnit> element.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Occurs if the <TimeUnit> element is not defined within the Quota policy. This element is mandatory and used to specify the unit of time applicable to the quota. The time interval can be in minutes, hours, days, weeks, or months.
policies.ratelimit.InvalidMessageWeight 500 Occurs if the value of the <MessageWeight> element specified through a flow variable is invalid (a non-integer value).
policies.ratelimit.QuotaViolation 500 The quota limit was exceeded. N/A

Deployment errors

Error name Cause Fix
InvalidQuotaInterval If the quota interval specified in the <Interval> element is not an integer, then the deployment of the API proxy fails. For example, if the quota interval specified is 0.1 in the <Interval> element, then the deployment of the API proxy fails.
InvalidQuotaTimeUnit If the time unit specified in the <TimeUnit> element is unsupported, then the deployment of the API proxy fails. The supported time units are minute, hour, day, week, and month.
InvalidQuotaType If the type of the quota specified by the type attribute in the <Quota> element is invalid, then the deployment of the API proxy fails. The supported quota types are default, calendar, flexi, and rollingwindow.
InvalidStartTime If the format of the time specified in the <StartTime> element is invalid, then the deployment of the API proxy fails. The valid format is yyyy-MM-dd HH:mm:ss, which is the ISO 8601 date and time format. For example, if the time specified in the <StartTime> element is 7-16-2017 12:00:00 then the deployment of the API proxy fails.
StartTimeNotSupported If the <StartTime> element is specified whose quota type is not calendar type, then the deployment of the API proxy fails. The <StartTime> element is supported only for the calendar quota type. For example, if the type attribute is set to flexi or rolling window in the <Quota> element, then the deployment of the API proxy fails.
InvalidTimeUnitForDistributedQuota If the <Distributed> element is set to true and the <TimeUnit> element is set to second then the deployment of the API proxy fails. The timeunit second is invalid for a distributed quota.
InvalidSynchronizeIntervalForAsyncConfiguration If the value specified for the <SyncIntervalInSeconds> element within the <AsynchronousConfiguration> element in a Quota policy is less than zero, then the deployment of the API proxy fails.
InvalidAsynchronizeConfigurationForSynchronousQuota If the value of the <AsynchronousConfiguration> element is set to true in a Quota policy, which also has asynchronous configuration defined using the <AsynchronousConfiguration> element, then the deployment of the API proxy fails.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. ratelimit.QT-QuotaPolicy.failed = true

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 ポリシーの比較