メニュー
Amazon API Gateway
開発者ガイド

API Gateway 使用量プランの作成と使用

API を作成し、テストして、デプロイすると、API Gateway 使用量プランを使用して、顧客への提供商品として拡張できます。ビジネス要件および予算の制約に合った承認済みのリクエストレートとクォータで、指定した顧客に、選択した API へのアクセスを許可する使用量プランを提供できます。

使用プランとは

使用量プランは、デプロイされた 1 つ以上の API ステージにアクセスできるユーザーを指定します。また、発信者が API にアクセスできる量と速度を示します。このプランでは、API キーを使用して API クライアントを特定し、個々のクライアント API キーに適用される設定可能なスロットリングとクォータ制限を使用して API ステージへのアクセスを測定します。

スロットリングは、各 API キーに適用されるリクエストレート制限を指示します。クォータは、指定した期間内に送信された API キーを持つリクエストの最大数です。 個別の API メソッドを、使用量プラン設定に基づく API キー認証を要求するように設定できます。API ステージは、API 識別子とステージ名によって識別されます。

注記

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

API Gateway で API キーを生成することも、外部ソースから API Gateway にインポートすることもできます。詳細については、「API Gateway コンソールを使用して API キーをセットアップする」を参照してください。

API キーのソースを公開

API の使用量プランを作成し、API メソッドで API キーを有効にする場合、受信リクエストには、適切な API キーが付属している必要があります。API Gateway は、受信リクエストから API キーを読み取り、使用量プランのキーと照合します。キーが一致すると、API Gateway は、プランのリクエスト制限とクォータに基づいてリクエストを調整します。それ以外の場合は、InvalidKeyParameter 例外がスローされます。その結果、発信者は 403 Forbidden レスポンスを受け取ります。

API Gateway が API キーから受け取るソースは 2 つあります。クライアント開発者にキーを配布し、API メソッドに API キーが必要な場合は、受信リクエストの X-API-Key ヘッダーとして API キーを渡すようにクライアントに依頼できます。これは API Gateway がヘッダーから読み取るため、HEADER ソースと呼ばれます。また、カスタム認証レスポンスの一部として API キーを返すカスタムオーソライザーを持つことができます。カスタム認証レスポンスの詳細については、「Amazon API Gateway カスタム認証からの出力」を参照してください。これは API Gateway がオーソライザー出力から読み取るため、AUTHORIZER ソースと呼ばれます。

API Gateway コンソールを使用して API キーのソースを選択するには、以下の手順に従います。

API Gateway コンソールを使用して、API の API キーのソースを選択するには:

  1. API Gateway コンソールにサインインします。

  2. 既存の API を選択するか、新しい API を作成します。

  3. プライマリナビゲーションペインで、選択した、または新しく作成した API の下で [Settings] を選択します。

  4. [Settings] ペインの [API Key Source] セクションの下で、ドロップダウンリストから [HEADER] または [AUTHORIZER] を選択します。

  5. [Save Changes] を選択します。

AWS CLI を使用して API の API キーのソースを選択するには、次のように update-rest-api コマンドを呼び出します。

aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER

クライアントが API キーを送信するには、上記の CLI コマンドで valueHEADER に設定します。

API Gateway REST API を使用して API の API キーのソースを選択するには、次のように restapi:update を呼び出します。

PATCH /restapis/fugvjdxtri/ HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20160603T205348Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "patchOperations" : [ { "op" : "replace", "path" : "/apKeySource", "value" : "HEADER" } ] }

オーソライザーに API キーを戻すには、前の patchOperations 入力で valueAUTHORIZER に設定します。

選択した API キーのソースタイプに応じて、以下のいずれかの手順を使用してヘッダーソースの API キー、または承認され返された API キーをメソッド呼び出しに使用します。

メソッド呼び出しにヘッダーソースの API キーを使用するには:

  1. 目的の API メソッドで、API を作成します。その API をステージにデプロイします。

  2. 新しい使用プランを作成するか、既存のものから選択します。デプロイされた API ステージを使用プランに追加します。使用プランに API キーをアタッチするか、プラン内の既存の API キーを選択します。選択した API キーの値を書き留めます。

  3. API キーを要求するよう API メソッドをセットアップします。

  4. 同じステージに API を再デプロイします。新しいステージに API をデプロイする場合は、必ず新しい API ステージをアタッチするように使用プランを更新します。

これでクライアントから、選択した API キーをヘッダー値とする x-api-key ヘッダーを指定しながら API メソッドを呼び出すことができるようになりました。

メソッド呼び出しに承認済みソースの API キーを使用するには:

  1. 目的の API メソッドで、API を作成します。その API をステージにデプロイします。

  2. 新しい使用プランを作成するか、既存のものから選択します。デプロイされた API ステージを使用プランに追加します。使用プランに API キーをアタッチするか、プラン内の既存の API キーを選択します。選択した API キーの値を書き留めます。

  3. トークンタイプのカスタム Lambda オーソライザーを作成します。認証レスポンスのルートレベルのプロパティとして usageIdentifierKey:{api-key} を含めます。ここで {api-key} は前のステップで説明した API キーの値です。

  4. API キーを要求するように API メソッドを設定し、メソッドでカスタムトークンオーソライザーも有効にします。

  5. 同じステージに API を再デプロイします。新しいステージに API をデプロイする場合は、必ず新しい API ステージをアタッチするように使用プランを更新します。

これでクライアントから、明示的に API キーを指定せずに、API キーを要求するメソッドを呼び出すことができるようになりました。オーソライザーから返される API キーは自動的に使用されます。

使用プランを設定する方法

以下の手順は、API 所有者として、顧客のために使用量プランを設定する方法を示します。

使用プランを設定するには

  1. 1 つ以上の API を作成し、API キーを要求するメソッドを設定して、ステージに API をデプロイします。

  2. API を使用して、API キーを生成し、アプリケーションの開発者 (顧客) にキーを配布します。

  3. 目的のスロットリングとクォータ制限を持つ使用プランを作成します。

  4. 使用プランに、選択した API ステージと API キーを関連付けます。

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

注記

使用量プランに API メソッドを含めるには、個別の API メソッドを、API キーを要求するように設定する必要があります。ユーザーの認証と許可のために、API キーを使用しないでください。IAM ロール、カスタムオーソライザーAmazon Cognito ユーザープールを使用します。

以下のセクションで、これらのタスクの詳細な手順を紹介します。

API Gateway コンソールを使用して API キーをセットアップする

API キーを設定するには、以下の作業を行います。

  • API キーを要求するよう API メソッドを設定します。

  • リージョンの API 用に API キーを作成またはインポートします。

API キーを設定するには、事前に API を設定し、それをステージにデプロイしている必要があります。

API Gateway コンソールを使用して API を作成し、デプロイする方法については、「Amazon API Gateway での API の作成」および「Amazon API Gateway での API のデプロイ」をそれぞれ参照してください。

メソッド上で API キーを要求する

次の手順では、API キーを要求する、API メソッドを設定する方法について説明します。

API キーを要求する API メソッドを設定するには

  1. AWS マネジメントコンソールにサインインして API Gateway コンソール (https://console.aws.amazon.com/apigateway/) を開きます。

  2. API Gateway メインナビゲーションペインで、[Resources] を選択します。

  3. [Resources] で、新しいメソッドを作成するか、既存のメソッドを選択します。

  4. [Method Request] を選択します。

  5. [Authorization Settings] セクションで、[API Key Required] に、[true] を選択します。

  6. チェックマークアイコンを選択して、設定を保存します。

  7. API をデプロイまたは再デプロイして要件を満たします。

API Key Required オプションを false に設定し、上記の手順を実行しない場合、そのメソッドに対しては API ステージに関連付けられている API キーが使用されません。

API キーの作成

使用量プランで使う API キーをすでに作成またはインポートした場合、この手順および次の手順を省略できます。

API キーを作成するには

  1. AWS マネジメントコンソールにサインインして API Gateway コンソール (https://console.aws.amazon.com/apigateway/) を開きます。

  2. API Gateway メインナビゲーションペインで、[API Keys] を選択します。

  3. [Actions] ドロップダウンメニューから、[Create API key] を選択します。

     使用プランの API キーの作成
  4. [Create API Key] で、以下の操作を行います。

    1. [Name] 入力フィールドに、API キー名 (例: MyFirstKey) を入力します。

    2. [Auto Generate] を選択してキー値を生成する API Gateway を取得するか、[Custom] を選択して、キーを手動で入力します。

    3. [Save] を選択します。

     使用プランの API キーの作成
  5. 必要に応じてさらに API キーを作成するには、前述の手順を繰り返します。

API キーのインポート

次の手順は、使用プランで API キーをインポートする方法について説明します。

API キーをインポートするには

  1. メインナビゲーションペインで、[API Keys] を選択します。

  2. [Actions] ドロップダウンメニューから、[Import API keys] を選択します。

  3. カンマ区切りのキーファイルをロードするには、[Select CSV File] を選択します。 また、キーを手動で入力できます。 ファイル形式の詳細については、「API Gateway API キーファイルの形式」を参照してください。

     API 使用量プランのエンティティ
  4. エラーが発生した場合、[Fail on warnings] を選択してインポートを停止するか、[Ignore warnings] を選択して、エラーが発生した場合に、有効なキーエントリのインポートを継続します。

  5. 選択した API キーのインポートを開始するには、[Import] を選択します。

API キーをセットアップしたので、「create and use a usage plan」に進むことができます。