メニュー
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 ステージを移行できます。

{ "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')。

使用プランの管理

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

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 リクエストを作成します。

    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 のエラーメッセージを記録します。ときどき起こるこのようなエラーは無視してかまいません。