Quota ポリシー

概要

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 プロダクトに設定された割り当て値を読み込みます。VerifyAPIKey フロー変数の詳細については、Verify 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 に設定した場合、明示的な <StartTime> 値を定義する必要があります。時間の値は、ローカル時間ではなく、GMT です。calendar タイプのポリシーに <StartTime> 値を設定しないと、Edge がエラーを返します。

各アプリの割り当てカウンタは、<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 件に達した場合、1 時間後にカウンタがリセットされるまで、以降の呼び出しはすべて拒否されます。

カウンタのリセット時間は、<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> 属性の値に基づいて複数のカウンタを維持できます。

たとえば、<Identifier> タグを使用して、クライアント ID ごとに別のカウンタを定義します。プロキシに対するリクエストが発生すると、クライアント アプリが上記の例のように 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>
    

これにより、Quota ポリシーで個々の client_id 値に独自のカウンタが定義されています。

クラス

    <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 ポリシーは、デフォルト、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 ポリシーを使用すると、想定よりも速く割り当ての上限に達する可能性があります。これはアンチパターンになります(The Book of Apigee Edge Antipatterns をご覧ください)。

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

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

時間の表記

Quota ポリシーで使用する時間はすべて協定世界時(UTC)で設定されます。

Quota ポリシーの時間表記は、国際規格 ISO 8601 で定義されている日付表記に準拠します。

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

時刻は時間、分、秒の形式(hours:minutes:seconds)で定義します。たとえば、23:59:59 は午前 0 時よりも 1 秒前を表します。

午前 0 時を表す場合、00:00:0024:00:00 を使用できます。つまり、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> の値に基づいてリセットするように割り当てを構成します。
calendar 省略可

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

属性 説明 デフォルト 要否
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 の値が使用されます。

デフォルト: なし
必須?: 省略可
型: 整数

属性

属性 説明 デフォルト 必須?
count

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

たとえば、count 属性の値が 100 で、Interval が 1、TimeUnit が month の場合、1 か月あたり 100 件のメッセージが上限になります。

2000 省略可
countRef

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

なし 省略可

<Allow> / <Class> 要素

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

<Class> 要素を使用するには、ref 属性を使用するフロー変数を <Class> タグに指定します。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>
    
デフォルト: なし
要否: 必須
型: 整数

属性

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

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

なし 省略可

<TimeUnit> 要素

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

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

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

String。minutehourdayweek または month から選択します。

属性

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

<StartTime> 要素

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

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

例:

    <StartTime>2017-7-16 12:00:00</StartTime>
    
デフォルト: なし
要否: typecalendar の場合は必須。
型:

String。ISO 8601 の日付と時刻の形式。

<Distributed> 要素

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

デフォルト値の 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> 要素を使用して、フロー変数に基づいて一意のカウンタを作成するポリシーを構成します。

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

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

String

属性

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

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

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

Quota の設定を取得する client_id 変数がないこともあります。たとえば、セキュリティ ポリシーが実施されていない場合に、この問題が発生します。Access Entity ポリシーで該当する API プロダクトの設定を取得し、ExtractVariables で値を抽出します。抽出したコンテキスト変数を Quota ポリシーで使用します。詳細については、Access Entity ポリシーをご覧ください。

なし 省略可

<MessageWeight> 要素

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

たとえば、POST メッセージを GET メッセージよりも 2 倍の重みで計算するとします。POST の MessageWeight に 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)。

エラー リファレンス

このセクションでは、このポリシーがトリガーとなってエラーが発生したときに返される障害コードとエラー メッセージ、そして Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成する上で重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

ポリシーの実行時に、以下のエラーが発生することがあります。

障害コード HTTP ステータス 原因 修正
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Quota ポリシー内に <Interval> 要素が定義されていない場合に発生します。この要素は必須であり、割り当ての対象期間を指定するために使用されます。この期間は、<TimeUnit> 要素で定義された分数、時間数、日数、週数、月数として定義できます。 build
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Quota ポリシー内に <TimeUnit> 要素が定義されていない場合に発生します。この要素は必須であり、割り当てに適用する時間単位を指定するために使用されます。期間は、分数、時間数、日数、週数、月数として定義できます。 build
policies.ratelimit.InvalidMessageWeight 500 フロー変数で <MessageWeight> 要素に無効な値(整数以外の値)が指定された場合に発生します。 build
policies.ratelimit.QuotaViolation 500 割り当て制限を超えました。 なし

デプロイエラー

エラー名 原因 修正
InvalidQuotaInterval <Interval> 要素に指定された割り当て間隔が整数でない場合、API プロキシのデプロイは失敗します。たとえば、<Interval> 要素に指定された割り当て間隔が 0.1 の場合、API プロキシのデプロイは失敗します。 build
InvalidQuotaTimeUnit <TimeUnit> 要素に指定された時間単位がサポートされないものである場合、API プロキシのデプロイは失敗します。サポートされている時間単位は minutehourdayweekmonth です。 build
InvalidQuotaType <Quota> 要素の type 属性によって指定された割り当てのタイプが無効な場合、API プロキシのデプロイは失敗します。サポートされている割り当てタイプは defaultcalendarflexirollingwindow です。 build
InvalidStartTime <StartTime> 要素に指定された時間の形式が無効な場合、API プロキシのデプロイは失敗します。有効な形式は yyyy-MM-dd HH:mm:ss です。これは、ISO 8601 の日付と時刻の形式です。たとえば、<StartTime> 要素に指定された時刻が 7-16-2017 12:00:00 の場合、API プロキシのデプロイは失敗します。 build
StartTimeNotSupported <StartTime> 要素が指定されていて、その割り当てタイプが calendar でない場合、API プロキシのデプロイは失敗します。<StartTime> 要素でサポートされている割り当てタイプは calendar だけです。たとえば、<Quota> 要素で type 属性が flexi または rolling window に設定されていると、API プロキシのデプロイは失敗します。 build
InvalidTimeUnitForDistributedQuota <Distributed> 要素が true に設定され、<TimeUnit> 要素が second に設定されていると、API プロキシのデプロイは失敗します。分散割り当ての場合、時間単位 second は無効です。 build
InvalidSynchronizeIntervalForAsyncConfiguration Quota ポリシーの <AsynchronousConfiguration> 要素の <SyncIntervalInSeconds> 要素に 0 より小さい値が指定されていると、API プロキシのデプロイに失敗します。 build
InvalidAsynchronizeConfigurationForSynchronousQuota Quota ポリシーの <AsynchronousConfiguration> 要素に true が設定され、<AsynchronousConfiguration> 要素で非同期構成が定義されていると、API プロキシのデプロイは失敗します。 build

障害変数

このポリシーがトリガーとなってエラーが発生した場合は、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラー表に記載されている障害の名前です。障害コードの最後の部分が障害名になります。 fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name は、障害をスローしたポリシーにユーザーが指定した名前です。 ratelimit.QT-QuotaPolicy.failed = true

エラー レスポンスの例

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

スキーマ

関連トピック

Reset Quota ポリシー

Spike Arrest ポリシー

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