API Gateway での REST API の使用量プランと API キー - Amazon API Gateway
使用量プランおよび API キーとはAPI Gateway で使用量プランを設定するステップAPI キーと使用量プランのベストプラクティス

API Gateway での REST API の使用量プランと API キー

API を作成、テストして、デプロイすると、API Gateway 使用量プランを使用して、顧客への提供商品として使用できるようになります。選択した API へのアクセスを顧客に許可する使用量プランと API キーを設定し、定義した制限とクォータに基づいてこれらの API へのリクエストのスロットリングを開始できます。これらは API、または API メソッドレベルで設定できます。

使用量プランおよび API キーとは

使用量プランは、デプロイ済みの API ステージとメソッドにアクセスできるユーザーを指定します。リクエストのスロットリングを開始するターゲットリクエストレートを設定することもできます (オプション)。このプランは、API キーを使用して、各キーの関連付けられた API ステージにアクセスできる API クライアントとユーザーを識別します。

API キーは、API へのアクセスを付与するために顧客のアプリケーションデベロッパーに配布する 英数字の文字列値です。API キーと Lambda オーソライザー、IAM ロール、または Amazon Cognito を一緒に使用して API へのアクセスを制御できます。ユーザーに代わって API Gateway が API キーを生成することも、CSV ファイルからインポートすることもできます。API Gateway で API キーを生成することも、外部ソースから API Gateway にインポートすることもできます。詳細については、「API Gateway コンソールを使用して API キーをセットアップする」を参照してください。

API キーには名前と値があります。(「API キー」と「API キー値」という用語は、しばしば同じ意味で使用されます。) この名前は 1024 文字を超えることはできません。値は、20〜128 文字の英数字の文字列です。例えば、apikey1234abcdefghij0123456789 です。

重要

API キー値は一意である必要があります。異なる名前で同じ値の 2 つの API キーを作成しようとすると、API Gateway はそれらを同じ API キーと見なします。

API キーを複数の使用量プランと関連付けることができます。使用量プランを複数のステージと関連付けることができます。ただし、指定された API キーは API の各ステージの 1 つの使用量プランにのみ関連付けることができます。

スロットリングの制限は、リクエストスロットリングを開始するターゲットポイントを設定します。これは API、または API メソッドレベルで設定できます。

クォータ制限は、指定した期間内に送信できる API キーを持つリクエストの目標最大数を設定します。個別の API メソッドを、使用量プラン設定に基づく API キー認可を要求するように設定できます。

スロットリングとクォータ制限は、使用プランのすべての API ステージについて集約される個々の API キーのリクエストに適用されます。

注記

使用量プランのスロットリングとクォータはハードリミットではなく、ベストエフォートベースで適用されます。場合によっては、クライアントは設定されているクォータを超えることがあります。コストの管理や API へのアクセスのブロックを行う際に使用プランのクォータやスロットリングに依存しないでください。AWS Budgets を使用してコストをモニタリングすること、および AWS WAF を使用して API リクエストを管理することを検討してください。

API Gateway で使用量プランを設定するステップ

以下のタスクでは、使用プランと API キーを設定するために必要なステップの概要を示します。ベストプラクティスについては、API キーと使用量プランのベストプラクティスを参照してください。

使用量プランと API キーを設定するには

  1. API を作成し、API キーを要求するように API メソッドごとにメソッドリクエストを設定します。次に、API をステージにデプロイします。

    使用量プランに API メソッドを含めるには、個別の API メソッドを、API キーを要求するように設定する必要があります。

    API キーを要求するメソッドを設定する方法の詳細については、「メソッドで API キーを要求する」を参照してください。

  2. API を使用するアプリケーションの開発者 (顧客) に配布する API キーを生成またはインポートします。使用量プランには API キーが必要です。

    API キーを生成またはインポートする方法の詳細については、「API キーを作成する」を参照してください。

  3. 必要なスロットルとクォータの制限を使用して使用量プランを作成し、API ステージと API キーを使用量プランに関連付けます。

    使用量プランを作成する方法の詳細については、「使用量プランを作成する」を参照してください。

API の呼び出し元は、API へのリクエストの x-api-key ヘッダーで、割り当てられた API キーを指定する必要があります。

使用量プランを作成して新しいステージと API キーに関連付ける完全な AWS CloudFormation テンプレートについては、「AWS CloudFormation を使用した API キーと使用量プランの作成および設定」を参照してください。

API キーと使用量プランのベストプラクティス

以下は、API キーおよび使用量プランを使用する場合の推奨されるベストプラクティスです。

重要

  • API キーを、API へのアクセスを制御するための認証または認可に使用しないでください。使用量プランに複数の API がある場合、その使用量プランの 1 つの API に対して有効な API キーを持つユーザーは、その使用量プランのすべての API にアクセスできます。代わりに、API へのアクセスを制御するには、IAM ロール、Lambda オーソライザー、または Amazon Cognito ユーザープールを使用します。

  • API Gateway が生成する API キーを使用します。API キーには機密情報を含めないでください。クライアントは通常、ログに記録できるヘッダーで機密情報を送信します。

  • デベロッパーポータルを使用して API を公開している場合は、顧客に表示していなくても、特定の使用量プランのすべての API は顧客からサブスクライブ可能であることに注意してください。

  • 場合によっては、クライアントは設定されているクォータを超えることがあります。コストを制御するために使用計画に依存しないでください。AWS Budgets を使用してコストをモニタリングすること、および AWS WAF を使用して API リクエストを管理することを検討してください。

  • API キーを使用量プランに追加した後で、更新オペレーションが完了するまでに数分かかる場合があります。