レスキューナウテックブログPublicationへの投稿
🚪

Amazon API Gateway（REST API）の「使用量プラン」と「APIキー」がすごい

ゆきなが
に公開
AWS
Amazon API Gateway
tech

はじめに

商用でAPI提供を検討したときに知ったAmazon API Gateway（REST API）の機能である「使用量プラン」と「APIキー」がすごく魅力的だったので、調べたことを共有します。

Amazon API Gateway（REST API）とは

AWSが提供しているAPI Gatewayサービスは現時点で4つありますが、その中でも認証やリクエスト、レスポンスなどを高度に制御できるRESTfulなAPIを構築できるのがREST APIです。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/http-api-vs-rest.html

使用量プランとは

REST APIが持つ機能である使用量プランは、「APIの利用制限を定義する設定」です。特定のクライアント（APIキー）グループに対して、以下の2つの主要な制限を設定できます。

  1. スロットリング (Throttling):

    • APIが処理できる秒間リクエスト数（RPS）を制限します。
    • レート: 定常的なリクエストレート（例: 100 RPS）。
    • バースト: 一時的に許可されるリクエストの最大値（例: 200リクエスト）。これにより、瞬間的なトラフィック増にもある程度対応できます。

  2. クォータ (Quota):

    • 特定の期間（日、週、月）における合計リクエスト数を制限します。
    • （例: 1ヶ月あたり1,000,000リクエストまで）。

これらのプランは、REST APIのステージ（例: dev, staging, prod）に関連付けて使用します。

メソッドスロットリング

さらに、かゆいところに手が届く！と思った機能として、使用量プランをステージに紐付けた後、個々のメソッド（例: GET /users, POST /items）ごとに個別のスロットリング設定も可能です。
これにより、「読み取り系（GET）はレートを高く、書き込み系（POST）はレートを低くする」といった、より詳細な制御が実現できます。

バーストが難しい

バーストの概念がわかりづらかったのでAIに聞いてみたらバケツをたとえにわかりやすい説明が返ってきたので引用します。すでに知っている方は読み飛ばして大丈夫です。

バーストとは

バーストは「リクエスト処理能力の貯金」のようなものだと考えると分かりやすいです。
REST APIは、この制限に「トークンバケット」というアルゴリズムを使っています。

  • レート (Rate): 1秒あたりにバケツに追加される「トークン（リクエスト許可証）」の数です。
  • バースト (Burst): そのバケツに貯めておけるトークンの最大容量です。

具体例: レート 100 RPS / バースト 200
この設定の場合、システムは以下のように動作します。

  1. 通常時: 1秒間に100枚の許可証がバケツに補充されます。もしその1秒間に来たリクエストが80件だけなら、80枚を消費し、残りの20枚はバケツに貯金されます。
  2. 貯金の上限: バケツには最大200枚までしか貯金できません（これがバースト値の役割です）。リクエストが全く来ない時間が続いても、バケツは200枚で満タンになります。
  3. スパイク（瞬間的な急増）発生:
  • バケツが満タン（200枚）の時に、ある瞬間に180リクエストが同時に来たとします。
  • これはレート（100）を大幅に超えていますが、バケツに貯金が180枚以上あるため、すべてのリクエストが成功します。
  • バケツの残りは20枚になります。
  1. スパイク直後:
  • バケツが空（または残りわずか）になった直後に、さらに150リクエストが来たとします。
  • 次の1秒で補充されるのは100枚（レート値）だけです。
  • したがって、100リクエストは成功しますが、残りの50リクエストは許可証が足りないため拒否され、クライアントには 429 Too Many Requests エラーが返されます。

まとめ
つまり「バースト」とは、レートで設定された平均処理能力（100 RPS）を、一時的にどれだけ上回ることを許容するかという「クッション」や「貯金箱のサイズ」を定義するものです。
これにより、常に100 RPSに張り付くようなトラフィックは制限しつつ、たまに発生する瞬間的なリクエストの急増（スパイク）にはエラーを返さず対応できる、という柔軟な制御が実現できます。

APIキーとは

APIキーは、「APIの利用者を識別するための文字列（トークン）」です。クライアントはリクエスト時にこのキーを x-api-key ヘッダーに含めて送信します。

REST APIは、このキーを受け取って以下の役割を果たします。

  • 識別: どのクライアントからのリクエストかを特定します。
  • 計測: APIキーごと（つまりクライアントごと）の利用状況を追跡します。
    • これは、API Gatewayの「使用量プラン」の詳細画面にある「使用量データをエクスポート」ボタンから行えます。
    • このボタンをクリックし、集計期間（開始日と終了日）を指定すると、各APIキーがその期間中に送信したリクエスト数を含むCSVまたはJSONファイルをダウンロードできます。これにより、クライアントごとの正確な利用量を把握できます。
  • 制御: 前述の使用量プランを紐づけることで、キーごとに設定された制限（スロットリングやクォータ）を適用します。

使用量データをエクスポート

「使用量データをエクスポート」の機能を探すのにいつも混乱するのですが、ついついAPIキーというメニューから入って行って見つからなくて迷子になるのですが、「使用量プラン」のほうにあるんですね。日毎にクォータを設定している使用量プランをCSVで出してみるとこんな感じでした。

apiKey,usagePlan,totalQuota,date,usedQuota
4oij****81,basic-plan,100000,2025-10-27,123
4oij****81,basic-plan,100000,2025-10-28,456
4oij****81,basic-plan,100000,2025-10-29,0
4oij****81,basic-plan,100000,2025-10-30,4

関連付けられたAPIキーというタブで、APIキーを選択すれば、そのAPIキーだけのエクスポートもできました。

設定の流れ

使用量プランやAPIキーを、管理コンソールで設定する流れは以下のようになります。

  1. 使用量プランを作成する:
    まず、「Basicプラン」「Proプラン」などの利用制限ルール（レートやクォータ）を定義します。
  2. プランをステージに関連付ける:
    作成した使用量プランを、対象のAPIステージ（例: prod）に関連付けます。「このルールは、prod 環境で使います」と宣言するイメージです。
  3. APIキーを作成する:
    次に、クライアント（利用者）に配布するAPIキーを生成します。
  4. APIキーをプランに追加する:
    (3)で作成したAPIキーを、(1)で作成した使用量プランに追加します。
  5. APIのメソッドリクエストの設定でAPIキーを必須にする
    最後に、APIキーを必須にしたいメソッドリクエストの設定をしてデプロイします。

この流れにより、「prodステージのAPIにおいて、このAPIキー（クライアントA）は、Basicプランの制限（月100万リクエストまで）に従う」という設定が完了します。

活用シナリオ

商用利用を想定した具体的な設計パターンを考えてみます。

シナリオ1: 汎用的なSaaSプラン (Basic / Pro)

多くのSaaSで提供される、階層型のプランです。

  • Basicプラン（月額1,000円）
    • クォータ: 100万リクエスト/月
    • レート: 10 RPS / バースト: 20 RPS
  • Proプラン（月額10,000円）
    • クォータ: 2000万リクエスト/月
    • レート: 100 RPS / バースト: 200 RPS

この場合、クライアント（契約者）ごとにAPIキーを発行し、契約したプラン（Basic or Pro）にそのキーを紐付けます。クライアントがプランをアップグレードしたら、管理コンソール（またはAPI）でキーの紐付けをProプランに変更します。

シナリオ2: 個別契約のEnterpriseプラン

リクエストが非常に多い特定のクライアント（大企業など）とは、個別のSLAを結ぶケースです。

  • A社 Enterpriseプラン
    • クォータ: 1億リクエスト/月
    • レート: 500 RPS / バースト: 1000 RPS
    • メソッドスロットリング: POST /heavy-process のみ 50 RPSに制限（プラン全体の500RPSを上書きして厳しくする）

この場合、「A社 Enterpriseプラン」という名前の使用量プランをA社専用に作成し、A社に発行したAPIキーをそこに関連付けます。

オーバーライドと、ステージ全体の制限について

オーバーライド

使用量プランのデフォルトのスロットリング設定は、メソットスロットリングで上書きできるそうです。

ステージ全体の制限

使用量プランのクォータや、それに紐づけたステージのメソットスロットリングで大量のアクセスを許可していたとしても、ステージ自体に設定された制限を超えてアクセスをすることはできないそうです。

おわりに

Amazon API Gateway（REST API）の「使用量プラン」と「APIキー」について、商用利用をイメージして整理しました。
SaaSのプランニングや、特定のクライアントへのAPI提供において高度な制御ができるようになります。これらの機能を自前実装することなしに、ただ使うだけでいいというのがすごい時代になりましたよね。（遠い目）

レスキューナウテックブログ
レスキューナウテックブログPublication

日本で唯一の危機管理情報を専門に取り扱う防災・BCPの専門企業、(株)レスキューナウです。当社で活躍するエンジニアの技術ブログを中心に公開していきます。

Discussion