Amazon API Gateway
開発者ガイド

API Gateway CLI および REST API を使用したテスト使用量プランの作成、設定、およびテスト

使用量プランを設定する前に、以下がすでに完了している必要があります。選択した API のメソッドで API キーが要求されるようセットアップ、API をステージにデプロイまたは再デプロイ、1 つ以上の API キーを作成またはインポート。詳細については、「API Gateway REST API を使用して API キーをセットアップする」を参照してください。

API Gateway REST API を使用して、使用量プランを設定する場合、使用量プランに追加された API を既に作成したと仮定して、次の手順を実行します。

デフォルトの使用プランへの移行

最初に使用量プランを作成する場合は、account:update を本文と共に呼び出して、使用量プランに選択した API キーに関連付けられた既存の API ステージを移行できます。

{ "patchOperations" : [ { "op" : "add", "path" : "/features", "value" : "UsagePlans" } ] }

API キーに関連付けられた API ステージの移行については、「API Gateway コンソールでのデフォルトの使用プランへの移行」を参照してください。

使用量プランの作成

次の手順は、使用量プランを作成する方法を説明します。

REST API を使用して、使用量プランを作成するには

  1. usageplan:create を呼び出して使用量プランを作成します。ペイロードで、プランの名前と説明、関連付けられた API ステージ、レート制限、およびクォータを指定します。

    結果として生じる使用プランの識別子を書き留めます。これは次の手順で必要です。

  2. 以下のいずれかを行います。

    1. usageplankey:create を呼び出して、使用量プランに API キーを追加します。ペイロードで keyIdkeyType を指定します。

      使用量プランに API キーを追加するには、一度に 1 つの API キーずつ、前の呼び出しを繰り返します。

    2. apikey:import を呼び出して、1 つ以上の API キーを指定した使用プランに直接追加します。リクエストペイロードは API キー値、関連付けられた使用量プランの識別子、キーが使用量プランに有効であることを示すブーリアン型フラグ、および、場合によっては、API キーの名前と説明を含む必要があります。

      apikey:import リクエストの次の例では、3 つの API キー (keyname、および description により識別される) が、1 つの使用量プラン (usageplanIds により識別される) に追加されます。

      POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1 Host: apigateway.us-east-1.amazonaws.com Content-Type: text/csv Authorization: ... key,name, description, enabled, usageplanIds abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt

      その結果、3 つの UsagePlanKey リソースが作成されて、UsagePlan に追加されます。

      この方法で API キーを複数の使用プランに追加することもできます。これを行うには、各 usageplanIds 列の値を、選択した使用量プランの識別子を含むカンマ区切り文字列に変更し、引用符で囲みます ("n371pt,m282qs" または 'n371pt,m282qs')。

      注記

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

REST API を使用して、使用量プランを管理する

使用量プランを管理するために、以下の API メソッドを使用できます。

  • usageplan:by-id を呼び出して、特定のプラン ID の使用量プランを取得します。利用可能な使用量プランを表示するには、apigateway:usage-plans を呼び出します。

  • usageplan:update を呼び出して、プランに新しい API ステージを追加し、プランの既存の API ステージを置き換え、プランから API ステージを削除するか、レート制限またはクォータを変更します。

  • usage:get を呼び出して、指定した期間内の使用状況データをクエリします。

  • usage:update を呼び出して、使用プランの現在の使用量の拡張を付与します。

次のコード例は、usageplan:update コマンドを呼び出して、メソッドレベルのスロットリング設定を追加、削除、または変更する方法を示しています。

注記

us-east-1 を変更して、API に適切なリージョン値を指定してください。

API ステージのすべてのメソッドにスロットリング制限を追加するには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "add", "path" : "/apiStages/<apiId:stageName>/throttle", "value" : "<value>" }

API ステージのすべてのメソッドにスロットリング制限を置き換えるには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "replace", "path" : "/apiStages/<apiId:stageName>/throttle", "value" : "<value>" }

個々のリソースとメソッドのスロットリングのレート制限を追加するには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "add", "path" : "/apiStages/<apiId:stageName>/throttle/<resourcePath/method>/rateLimit", "value" : "<value>" }

個々のリソースとメソッドのスロットリングのレート制限を置き換えるには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "replace", "path" : "/apiStages/<apiId:stageName>/throttle/<resourcePath/method>/rateLimit", "value" : "<value>" }

個々のリソースとメソッドのスロットリングのバースト制限を追加または置換するには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "add", "path" : "/apiStages/<apiId:stageName>/throttle/<resourcePath/method>/burstLimit", "value" : "<value>" }

個々のリソースとメソッドのスロットリングのバースト制限を置き換えるには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "replace", "path" : "/apiStages/<apiId:stageName>/throttle/<resourcePath/method>/burstLimit", "value" : "<value>" }

API のメソッドレベルのスロットリング設定を削除するには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "remove", "path" : "/apiStages/<apiId:stageName>/throttle", "value" : "<value>" }

個々のリソースとメソッドのメソッドレベルのスロットリング設定を追加または置換するには、次のペイロードで usageplan:update を呼び出します。

{ "op" : "remove", "path" : "/apiStages/<apiId:stageName>/throttle/<resourcePath/method>", "value" : "<value>" }

AWS CLI を使用して、使用量プランを管理する

次のコード例は、update-usage-plan コマンドを呼び出して、メソッドレベルのスロットリング設定を追加、削除、または変更する方法を示しています。

注記

us-east-1 を変更して、API に適切なリージョン値を指定してください。

個々のリソースとメソッドのスロットリングのレート制限を追加または置換するには。

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/rateLimit",value="0.1"

個々のリソースとメソッドのスロットリングのバースト制限を追加または置換するには。

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/burstLimit",value="1"

個々のリソースとメソッドのメソッドレベルのスロットリング設定を追加または置換するには。

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>",value=""

API のメソッドレベルのスロットリング設定をすべて削除するには。

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle ",value=""

Pet Store サンプル API を使用する例を次に示します。

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'

使用プランのテスト

例として、例から API Gateway API を構築する で作成される PetStore API を使用します。API は Hiorr45VR...c4GJc の API キーを使用するように設定されると仮定します。以下の手順では、使用プランをテストする方法について説明します。

使用プランをテストするには

  • 使用量プランの API (例: GET) の、/pets クエリパラメータを使用して、Pets リソース (?type=...&page=...) で、xbvxlpijch リクエストを作成します。

    GET /testStage/pets?type=dog&page=1 HTTP/1.1 x-api-key: Hiorr45VR...c4GJc Content-Type: application/x-www-form-urlencoded Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com X-Amz-Date: 20160803T001845Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}

    注記

    API Gateway の execute-api コンポーネントにこのリクエストを送信して、必要な x-api-key ヘッダーで、必要な API キー (例: Hiorr45VR...c4GJc) を提供する必要があります。

    正常なレスポンスでは、200 OK ステータスコード、およびバックエンドからリクエストされた結果を含むペイロードが返されます。x-api-key ヘッダーの設定を忘れるか、不正なキーを設定した場合は、403 Forbidden レスポンスが表示されます。ただし、必要な API キーにメソッドを設定しなかった場合は、200 OK ヘッダーを正しく設定したかどうかにかかわらず、x-api-key レスポンスが表示され、使用量プランのスロットリングとクォータ制限はバイパスされます。

    ときどき、API Gateway がリクエストに使用量プランスロットリング制限またはクォータを適用できない内部エラーが発生することがあり、この場合 API Gateway は使用量プランで指定されたスロットリング制限またはクォータを適用せずにリクエストを処理します。しかし、CloudWatch に Usage Plan check failed due to an internal error というエラーメッセージが記録されます。ときどき起こるこのようなエラーは無視してかまいません。