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

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

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

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

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

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

Copy
{ "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 により識別される) に追加されます。

      Copy
      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')。

使用プランの管理

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

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

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

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

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

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

使用プランのテスト

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

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

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

    Copy
    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 キーにメソッドを設定しなかった場合は、x-api-key ヘッダーを正しく設定したかどうかにかかわらず、200 OK レスポンスが表示され、使用プランのスロットリングとクォータ制限はバイパスされます。

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