Rate Limiting plugin

Rate Limiting plugin（作成画面での表示名は Rate Limit by Request Count、技術名 limit-count、Traffic Control グループ）は、一定の時間枠内の API への request 数を制限します。上限を超えた request は拒否されます。

ユースケース

Rate Limiting plugin は、トラフィックの急増時、不具合のあるクライアントが request をループで再送信したとき、不正利用や攻撃があったときに、バックエンドを過負荷から守ります。

主なケース:

• 各クライアントの IP アドレスに、時間枠あたり最大 N 件の request を許可する。
• 認証済みの Consumer ごとに制限する: 各 Consumer は他に影響を与えずに独自の上限を持ちます。
• カスタムヘッダーの値で制限する（例: X-API-Key ヘッダーの API キー）。
• API Gateway が複数のノードで稼働しており、クラスター全体で正確な共通の上限が必要: 各ノードで数える代わりに、policy を redis に設定します。

警告

Consumer ごとに制限する（limit_by を consumer に設定する）には、Route / Service に JWT Auth などの認証 plugin がすでに必要です。認証されていない request には数える対象の Consumer がありません。

Rate Limiting plugin を作成する

Rate Limiting plugin を作成するには、次の手順を実行します。

1. 左側のメニューで API Gateway → Plugin を選択し、右上で API Gateway を選択して New plugin をクリックし、Add plugin ポップアップで Rate Limiting を選択します。Route / Service の Plugins タブから追加することもできます。Plugin の追加を参照してください。

2. Basic Information セクションで Display Name を入力します。Basic Informationを参照してください。

3. Configuration セクションを選択します。フォームには 8 つの属性と Quick Start Templates ブロックが表示されます。request_count_limit フィールドはまだ空（灰色の 100 はヒントにすぎません）のため、値を入力するまで Configuration セクションに赤い ⓘ アイコンが表示されます。

属性	必須	説明
request_count_limit	Y	1 つの time_window で許可する request の最大数です。
time_window	Y	カウントする時間枠の長さです: second、minute、hour、day。デフォルトは minute です。
limit_by	Y	request をカウンターにまとめる方法です。limit_by でカウントのキーを選ぶを参照してください。デフォルトは all です。
error_code	N	上限を超えたときに返す HTTP コードです。デフォルトは 429 です。
error_message	N	エラーコードとともに返すメッセージです。デフォルトは Too many requests, please try again later. です。
show_rate_limit_headers	N	response に X-RateLimit-Limit と X-RateLimit-Remaining ヘッダーを追加し、クライアントが残りの上限を把握できるようにします。デフォルトは true です。
continue_on_storage_failure	N	カウンターのストレージに障害が発生したときに、request をブロックせずに通過させます。オンにすると、上限の正確さよりも可用性を優先します。デフォルトは false です。
policy	N	カウンターの保存場所です: local（API Gateway の各ノードで個別にカウント）または redis（クラスター全体で共有）。デフォルトは local です。

必要に応じて、Attribute (8) をクリックして属性を追加します。

limit_by が header の場合:

属性	必須	説明
header_name	Y	クライアントを識別する HTTP ヘッダーの名前です（例: X-API-Key）。limit_by を header に設定すると、このフィールドが自動的に（空で）追加されます。

policy が redis の場合:

属性	必須	説明
redis_host	Y	Redis サーバーのアドレスです。
redis_port	N	Redis サーバーのポートです。
redis_password	N	Redis のパスワードです（ある場合）。
redis_database	N	使用する Redis データベースのインデックスです。
redis_cluster_name	N	ノードが属する Redis クラスターの名前です。
connection_timeout	N	エラーとみなすまで Redis を待つ時間（ミリ秒）です。
enable_ssl	N	Redis への接続を暗号化します。
verify_ssl_certificate	N	Redis サーバーの証明書を検証します。enable_ssl がオンの場合に使います。

複数の制限を同時に設定する: + Add Another Limit をクリックすると、同じ plugin に request_count_limit / time_window の組を追加できます。たとえば、急増対策の 100 request / 分と、総使用量の上限となる 5000 request / 日を組み合わせます。制限が 2 つ以上になると、組は limits 配列に移り、他の属性（limit_by、error_code、policy など）はすべての制限に適用されます。

Quick Start Templates を使う（任意）: カードの Use Template をクリックします。

テンプレート	使用する場面
Basic API Protection（Local · Single Limit）	IP ごとに制限し、カウンターを各ノードに保存します。外部コンポーネントは不要です。公開 API を急増から守るのに適しています。
High-Availability Shared Quota（Redis · Multi-Node）	API Gateway クラスター全体が Redis の 1 つのカウンターを共有します。複数ノードの本番環境におすすめです。policy が local の場合は各ノードが個別にカウントするため、実際の上限はノード数倍になります。

警告

High-Availability Shared Quota テンプレートは、プレースホルダーとして your-redis-host を入力します。Create をクリックする前に、実際の Redis のアドレスに置き換えてください。

4. Scope セクションを選択し、Global または Scoped を選んで、制限する Route / Service を割り当てます。Scopeを参照してください。

5. Create をクリックします。Plugin created successfully というメッセージが表示され、選択した範囲に対応する Applied to 列とともに plugin が一覧に表示されます。

limit_by でカウントのキーを選ぶ

limit_by は、どの request が 1 つのカウンターを共有するかを決めます。

制限の単位	limit_by	備考
各クライアントの IP アドレス	ip	公開 API で最も一般的です。同じ NAT / プロキシの背後にあるクライアントは 1 つの IP としてカウントされます。
認証済みの各 Consumer	consumer	Route / Service で認証 plugin が先に実行される必要があります。
カスタムヘッダーの値	header	header_name にヘッダー名を入力します（例: X-API-Key）。
IP と Consumer の組み合わせ	ip_consumer	（IP、Consumer）の組ごとに 1 つのカウンターです。1 つのアカウントが複数の場所から使われる場合に、consumer より厳しくなります。
全トラフィックで 1 つの上限を共有	all	注意: この場合、request_count_limit は各クライアントの上限ではなく、全クライアントの合計の上限になります。これがデフォルトです。

注記

Scope と limit_by は独立した 2 つの層です。Scope は plugin を適用する Route / Service を決め、limit_by はその Scope 内の request の間でカウンターをどう分けるかを決めます。

設定例

フォームを最初に開いたときの設定（request_count_limit なし）:

{
  "time_window": "minute",
  "limit_by": "all",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "local"
}

Basic API Protection テンプレートで、IP ごとに 100 request / 分:

{
  "request_count_limit": 100,
  "time_window": "minute",
  "limit_by": "ip",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "local"
}

High-Availability Shared Quota テンプレートで、カウンターを Redis で共有:

{
  "request_count_limit": 100,
  "time_window": "minute",
  "limit_by": "ip",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "redis",
  "redis_host": "your-redis-host",
  "redis_port": 6379,
  "redis_password": "",
  "redis_database": 0,
  "connection_timeout": 1000,
  "enable_ssl": false,
  "redis_cluster_name": ""
}

IP ごとに 2 つの制限を同時に設定（100 request / 分と 5000 request / 日）:

{
  "limit_by": "ip",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "local",
  "limits": [
    {
      "request_count_limit": 100,
      "time_window": "minute"
    },
    {
      "request_count_limit": 5000,
      "time_window": "day"
    }
  ]
}

認証済みの Consumer ごとに 1000 request / 時間:

{
  "request_count_limit": 1000,
  "time_window": "hour",
  "limit_by": "consumer",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "local"
}

X-API-Key ヘッダーで 500 request / 分に制限:

{
  "request_count_limit": 500,
  "time_window": "minute",
  "limit_by": "header",
  "header_name": "X-API-Key",
  "error_code": 429,
  "error_message": "Too many requests, please try again later.",
  "show_rate_limit_headers": true,
  "continue_on_storage_failure": false,
  "policy": "local"
}

動作を確認する

time_window 内で request_count_limit を超えるまで、Route / Service 経由で API を繰り返し呼び出します。上限を超えた request には error_code（デフォルト 429）と error_message が返ります。show_rate_limit_headers がオンの場合は、すべての response に X-RateLimit-Limit と X-RateLimit-Remaining が付くため、ブロックされるのを待たずに残りの呼び出し回数がわかります。

よくある問題

エラー	原因	対処方法
Configuration に赤い ⓘ アイコンが表示され、Create が無効	request_count_limit が空です（灰色の数字はヒントにすぎません）	request_count_limit に値を入力します。
複数ノードで実際の上限が設定より多くなる	policy が local のため、各ノードが個別にカウントしています	クラスター全体で 1 つのカウンターを共有するように、policy を redis に設定します。
consumer による制限が機能しない	Route / Service に認証 plugin がありません	同じ Route / Service に JWT Auth などの認証 plugin を追加します。

次のステップ

• Proxy Rewrite plugin
• Plugin の概要