
概要
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>
type
が calendar
に設定された 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、calendar
、flexi
、rollingwindow
というさまざまなタイプのポリシーをサポートしています。次の表に示すように、ポリシーのタイプによって割り当てカウンタの開始時間とリセット条件が異なります。
時間単位 | デフォルトまたは 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: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">
以下の属性は、このポリシーに固有のものです。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
型 |
割り当てカウンタが割り当て使用量を確認するタイミングと方法の判定に使用されます。詳細については、Quota ポリシーのタイプをご覧ください。
有効な値は次のとおりです。
|
カレンダー | 省略可 |
次の表は、すべてのポリシーの親要素に共通の属性を示したものです。
属性 | 説明 | デフォルト | プレゼンス |
---|---|---|---|
name |
ポリシーの内部名。 必要に応じて |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗してもフローの実行を続けるには |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性はサポートが終了しています。 |
false | 非推奨 |
<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
の値が使用されます。
デフォルト: | なし |
要否: | 省略可 |
型: | Integer |
属性
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
count |
割り当てのメッセージ数を指定します。 たとえば、 |
2000 | 省略可 |
countRef |
割り当てのメッセージ カウントを含むフロー変数を指定します。
|
なし | 省略可 |
<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_time
と off_peak_time
という 2 つの割り当てカウンタが維持されます。
デフォルト: | なし |
要否: | 省略可 |
型: | なし |
属性
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
class |
割り当てカウンタの名前を定義します。 |
なし | 必須 |
count | カウンタの割り当て制限を指定します。 | なし | 必須 |
<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>
デフォルト: | なし |
要否: | 必須 |
型: | Integer |
属性
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
ref |
割り当ての間隔を含むフロー変数を指定します。 |
なし | 省略可 |
<TimeUnit> 要素
割り当てに適用する時間単位を指定します。
たとえば、Interval
が 24
で、TimeUnit
が hour
の場合、割り当ては 24 時間ごとに計算されます。
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
デフォルト: | なし |
要否: | 必須 |
型: |
文字列。 |
属性
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
ref | 割り当ての時間単位を含むフロー変数を指定します。ref は明示的な間隔の値よりも優先されます。ランタイムに ref が解決されない場合、値が使用されます。 |
なし | 省略可 |
<StartTime> 要素
type
が calendar,
に設定されている場合、割り当てカウンタがカウントを開始する日時を指定します。いずれかのアプリからリクエストが受信されたかどうかは関係ありません。
type
が明示的に calendar,
に設定されており、フロー変数への参照を使用できない場合、明示的な StartTime
を指定する必要があります。type
値が設定されていない場合に StartTime
値を指定すると、エラーが発生します。
例:
<StartTime>2017-7-16 12:00:00</StartTime>
デフォルト: | なし |
要否: | type が calendar に設定されている場合は必須。 |
型: |
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>
要素を使用します。
この要素を使用しない場合、ポリシーは割り当てに適用された 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 プロダクトなどに固有のものです。 アプリを一意に識別するために最もよく使用される 状況によっては、セキュリティ ポリシーが設定されていない場合など、 |
なし | 省略可 |
<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"/>
デフォルト: | なし |
要否: | 省略可 |
型: |
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 ポリシータイプが |
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. |
build |
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. |
build |
policies.ratelimit.InvalidMessageWeight |
500 | Occurs if the value of the <MessageWeight> element specified through a flow variable
is invalid (a non-integer value). |
build |
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.
|
build |
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 .
|
build |
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 .
|
build |
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.
|
build |
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.
|
build |
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. |
build |
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. |
build |
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. |
build |
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>