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 を使用して、使用量プランを作成するには
-
usageplan:create
を呼び出して、使用量プランを作成します。ペイロードで、プランの名前と説明、関連付けられた API ステージ、レート制限、およびクォータを指定します。結果として生じる使用プランの識別子を書き留めます。これは次の手順で必要です。
-
次のいずれかを行ってください。
-
usageplankey:create
を呼び出して、使用量プランに API キーを追加します。ペイロードでkeyId
とkeyType
を指定します。使用量プランに API キーを追加するには、一度に 1 つの API キーずつ、前の呼び出しを繰り返します。
-
apikey:import
を呼び出して、指定した使用量プランに 1 つ以上の API キーを直接追加します。リクエストペイロードは API キー値、関連付けられた使用量プランの識別子、キーが使用量プランに有効であることを示すブーリアン型フラグ、および、場合によっては、API キーの名前と説明を含む必要があります。apikey:import
リクエストの次の例では、3 つの API キー (key
、name
、および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 つの使用量プランにのみ関連付けることができます。
-
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}}"'
使用量プランのテスト
例として、チュートリアル: サンプルをインポートして REST 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
コンポーネントにこのリクエストを送信して、必要なHiorr45VR...c4GJc
ヘッダーで、必要な API キー (例:x-api-key
) を提供する必要があります。正常なレスポンスでは、
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
のエラーメッセージが記録されます。ときどき起こるこのようなエラーは無視してかまいません。