API GatewayのAPIキーと使用量プランについて調べてみた

CX事業本部の小倉です。

API GatewayのAPIキー&使用量プラン機能について調べる機会があったのでまとめてみました。

何ができるの？

API GatewayからAPIキーを発行することで、以下が可能になります。

• APIキーを持つユーザのみアクセス可能なAPIを作成できる
• 使用量プランを作成することで、APIキーにクォータ（アクセス可能回数）、レート（アクセス頻度）、バーストを設定できる
  • （レート、バーストの制限値はAWSアカウント全体、APIステージ毎にも元々存在します）
• APIキー毎のアクセス回数を取得できる

やってみる

API GatewayがAPIキーを受け取る方法は、ヘッダ経由とLambdaオーソライザ経由の二種類があるようです。
今回はヘッダ(x-api-key)から受け取る方法で作成してみます。

REST APIを作成

マネジメントコンソールからREST APIを作成します。 api-key-test という名前で作成しました。

作成したAPIに、/testというリソースを追加し、GETメソッドを作成します。
テスト用のLambda関数を呼び出すように設定しておきます。

GETメソッドのメソッドリクエストを選択して、APIキーの必要性をtrueに変更します。

これでこのメソッドは実行時にAPIキーが必要なメソッドになりました。 APIをデプロイして確認してみます。
（リクエストの送信にはIntelliJ IDEAのHTTPクライアントを使用しました）

devステージにデプロイし、/testへリクエストを送信すると、応答が403 Forbiddenとなりました。

APIキーの作成

それではAPIキーを作成します。 API Gateway -> APIキー -> APIキーの作成から、APIキーを作成します。

作成後の画面を確認してみると、APIキーが発行されているのがわかります。
（まだこの段階では先程作成した/testにはアクセスできません）

使用量プランの作成

次に使用量プランを作成します。
使用量プランの作成では、レート（1秒あたりのリクエスト数）や、
クォータ（特定の期間(日or週or月）内のリクエスト可能数）を設定することが出来ます。
今回は一日10回のリクエスト数制限を設定してみました。

今回は設定していませんが、使用量プランの中で更にリソース・メソッド毎にレート、バーストの設定をすることもできるようです。

使用量プラン、APIステージ、APIキーの関連付けを設定

使用量プランをAPIをAPIのステージに関連付けます。
先程作成した使用量プランを、devステージに関連付けました。

次に、使用量プランとAPIキーを関連付けます。
先程作成した使用量プランを、作成しておいたtest-api-keyと関連付けます。

ここまでで、以下の内容を準備しました。

アクセスしてみる

それではもう一度APIにアクセスしてみます。 リクエストヘッダx-api-keyに、作成したAPIキーの値を指定して送信します。

今度は無事に成功の応答が返却されてきました。

アクセス回数を取得してみる

APIキー毎のアクセス回数は、期間を指定しJSON形式、CSV形式でダウンロードすることが可能です。

JSON形式の場合、1つ目の値はアクセス回数、2つ目はアクセス可能回数の残数です。

CSV形式の場合は、クォータの値と、アクセス回数で出力されました。

この日付はUTCとなります。またアクセスしてから反映されるまで少し時間が掛かる場合があるようです。

アクセス回数を追加する

アクセス回数がクォータの値に達すると、以降のリクエストではエラーが応答されるようになります。
こうなった場合、リクエスト可能な数を追加することで再びアクセス可能になります。

使用量プランの挙動について

使用量プランによる制限は、使用量プランとAPIキーの組み合わせに対して実行されます。

複数のAPIキーを一つのプランに関連付けた場合、APIキー単位に制限が行われます。

異なるAPIステージで、同じ使用量プランとAPIキーを設定した場合、アクセス可能数は共有されます。

この場合、2つのステージで合計1日10回アクセス可能です。

ステージが別であれば同じAPIキーに異なる使用量プランを設定可能です。
開発環境ならば無制限にアクセス可能、というような設定が可能です。
（同じステージ内で、APIキーを複数の使用量プランに関連付けることはできません。）

気をつけたいポイント

使用量プランの変更

APIキーに関連付けたプランを変更しようとすると、一度現在のプランとの関連付けを削除しないと
新しいプランとの関連付けを設定できませんでした。
ただし関連付けを削除してしまうと、過去の使用量プランでのアクセス数は取得できなくなりました。
APIキー提供先に対して使用量プランを変更する場合は、新たなAPIキーを発行したほうがよさそうです。

エラー時のアクセス回数カウントの扱い

API Gatewayから呼び出したLambda関数がエラーを返した場合もAPIキーと使用量プランのアクセス回数には計上されますので注意してください。

APIキーをアクセス制御に使用しない

APIキーを使ってアクセスすると、他に認可設定を行っていない場合
APIキーの必要性:trueに設定されている全てのメソッドにアクセス可能になります。
APIキーはあくまでアクセスの計測目的に使用し、アクセス制御は別途Cognito等で実施するようにしましょう。

参考資料

• API キーを使用した使用量プランの作成と使用