# API Gateway での REST API の使用量プランと API キー
API を作成、テストして、デプロイすると、API Gateway 使用量プランを使用して、顧客への提供商品として使用できるようになります。選択した API へのアクセスを顧客に許可する使用量プランと API キーを設定し、定義した制限とクォータに基づいてこれらの API へのリクエストのスロットリングを開始できます。これらは API、または API メソッドレベルで設定できます。
## 使用量プランおよび API キーとは
*使用量プラン*は、デプロイ済みの API ステージとメソッドにアクセスできるユーザーを指定します。リクエストのスロットリングを開始するターゲットリクエストレートを設定することもできます (オプション)。このプランは、API キーを使用して、各キーの関連付けられた API ステージにアクセスできる API クライアントとユーザーを識別します。
*API キー*は、API へのアクセスを付与するために顧客のアプリケーションデベロッパーに配布する 英数字の文字列値です。API キーと [Lambda オーソライザー](apigateway-use-lambda-authorizer.md)、[IAM ロール](permissions.md)、または [Amazon Cognito](apigateway-integrate-with-cognito.md) を一緒に使用して API へのアクセスを制御できます。ユーザーに代わって API Gateway が API キーを生成することも、[CSV ファイル](api-key-file-format.md)からインポートすることもできます。API Gateway で API キーを生成することも、外部ソースから API Gateway にインポートすることもできます。詳細については、「[API Gateway で REST API の API キーをセットアップする](api-gateway-setup-api-keys.md)」を参照してください。
API キーには名前と値があります。(「API キー」と「API キー値」という用語は、しばしば同じ意味で使用されます。) この名前は 1024 文字を超えることはできません。値は、20〜128 文字の英数字の文字列です。例えば、`apikey1234abcdefghij0123456789` です。
**重要**
API キー値は一意である必要があります。異なる名前で同じ値の 2 つの API キーを作成しようとすると、API Gateway はそれらを同じ API キーと見なします。
API キーを複数の使用量プランと関連付けることができます。使用量プランを複数のステージと関連付けることができます。ただし、指定された API キーは API の各ステージの 1 つの使用量プランにのみ関連付けることができます。
*スロットリングの制限*は、リクエストスロットリングを開始するターゲットポイントを設定します。これは API、または API メソッドレベルで設定できます。
*クォータ制限*は、指定した期間内に送信できる API キーを持つリクエストの目標最大数を設定します。個別の API メソッドを、使用量プラン設定に基づく API キー認可を要求するように設定できます。
スロットリングとクォータ制限は、使用プランのすべての API ステージについて集約される個々の API キーのリクエストに適用されます。
**注記**
使用量プランのスロットリングとクォータはハードリミットではなく、ベストエフォートベースで適用されます。場合によっては、クライアントは設定されているクォータを超えることがあります。コストの管理や API へのアクセスのブロックを行う際に使用プランのクォータやスロットリングに依存しないでください。[AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) を使用してコストをモニタリングすること、および [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) を使用して API リクエストを管理することを検討してください。
## API キーと使用量プランのベストプラクティス
以下は、API キーおよび使用量プランを使用する場合の推奨されるベストプラクティスです。
**重要**
API キーを、API へのアクセスを制御するための認証または認可に使用しないでください。使用量プランに複数の API がある場合、その使用量プランの 1 つの API に対して有効な API キーを持つユーザーは、その使用量プランの*すべて*の API にアクセスできます。代わりに、API へのアクセスを制御するには、IAM ロール、[Lambda オーソライザー](apigateway-use-lambda-authorizer.md)、または [Amazon Cognito ユーザープール](apigateway-integrate-with-cognito.md)を使用します。
API Gateway が生成する API キーを使用します。API キーには機密情報を含めないでください。クライアントは通常、ログに記録できるヘッダーで機密情報を送信します。
+ デベロッパーポータルを使用して API を公開している場合は、顧客に表示していなくても、特定の使用量プランのすべての API は顧客からサブスクライブ可能であることに注意してください。
+ 場合によっては、クライアントは設定されているクォータを超えることがあります。コストを制御するために使用計画に依存しないでください。[AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) を使用してコストをモニタリングすること、および [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) を使用して API リクエストを管理することを検討してください。
+ API キーを使用量プランに追加した後で、更新オペレーションが完了するまでに数分かかる場合があります。
# API Gateway で API キーソースを選択する
使用量プランを API と関連付けて API メソッドで API キーを有効にする場合、API への各受信リクエストには [API キー](api-gateway-basic-concept.md#apigateway-definition-api-key)が含まれている必要があります。API Gateway はキーを読み取り、使用量プランのキーと照合します。一致する場合、API Gateway は、プランのリクエスト制限とクォータに従ってリクエストを調整します。それ以外の場合は、`InvalidKeyParameter` 例外がスローされます。その結果、発信者は `403 Forbidden` レスポンスを受け取ります。
API Gateway は 2 つのソースのいずれかから API キーを受け取ることができます。
**`HEADER`**
API キーを顧客に配布して、各受信リクエストの `X-API-Key` ヘッダーとして API キーを渡す必要があります。
**`AUTHORIZER`**
この認可レスポンスの一部として API キーを返す Lambda オーソライザーを使用することができます。認可レスポンスの詳細については、「[API Gateway Lambda オーソライザーからの出力](api-gateway-lambda-authorizer-output.md)」を参照してください。
**注記**
考慮すべきベストプラクティスについては、「[API キーと使用量プランのベストプラクティス](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices)」を参照してください。
次の手順は、API の API キーソースを選択する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
**API の API キーソースを選択するには**
1. [API Gateway コンソール] にサインインします。
1. 既存の API を選択するか、新しい API を作成します。
1. メインナビゲーションペインで、**[API の設定]** を選択します。
1. **[API の詳細]** セクションで **[編集]** を選択します。
1. **API キーソースで**、ドロップダウンリストから `Header` または `Authorizer` を選択します。
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
次の [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) コマンドは、API キーソースを `AUTHORIZER` に設定するように API を更新します。
```
aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER
```
クライアントが API キーを送信するように指定するには、前のコマンドで `value` を `HEADER` に設定します。
------
#### [ REST API ]
API Gateway REST API を使用して API の API キーのソースを選択するには、次のように [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) を呼び出します。
```
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" : "/apiKeySource",
"value" : "HEADER"
}
]
}
```
オーソライザーに API キーを戻すには、前の `value` 入力で `AUTHORIZER` を `patchOperations` に設定します。
------
# API Gateway API キーファイルの形式
API Gateway はカンマ区切り値 (CSV) 形式の外部ファイルから API キーをインポートでき、インポートされたキーを 1 つ以上の使用量プランに関連付けます。インポートされたファイルには、`Name` および `Key` 列が含まれている必要があります。次の例のように、列のヘッダー名は大文字小文字を区別せず、順序は任意です。
```
Key,name
apikey1234abcdefghij0123456789,MyFirstApiKey
```
`Key` 値は、20～128 文字にする必要があります。`Name` 値は 1024 文字を超えることはできません。
次の例のように、API キーファイルには、`Description`、`Enabled`、または `UsagePlanIds` 列もあります。
```
Name,key,description,Enabled,usageplanIds
MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b
```
次の例のように、キーが複数の使用量プランに関連付けられる場合、`UsagePlanIds` 値は、二重引用符または一重引用符で囲まれたカンマ区切り文字列の使用量プラン ID です。
```
Enabled,Name,key,UsageplanIds
true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr"
```
認識されない列は許可されますが、無視されます。デフォルト値は、空の文字列または `true` ブール値です。
同じ API キーを複数回インポートすることができ、最新バージョンは前のキーを上書きします。`key` 値が同じ場合、2 つの API キーは同一です。
**注記**
考慮すべきベストプラクティスについては、「[API キーと使用量プランのベストプラクティス](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices)」を参照してください。
# API Gateway で REST API の API キーをセットアップする
API キーを設定するには、以下の作業を行います。
+ API キーを要求するよう API メソッドを設定します。
+ リージョンの API 用に API キーを作成またはインポートします。
API キーを設定するには、事前に API を設定し、それをステージにデプロイしている必要があります。API キー値は、作成後に変更することはできません。
API Gateway コンソールを使用して API を作成し、デプロイする方法については、「[API Gateway で REST API を開発する](rest-api-develop.md)」および「[API Gateway で REST API をデプロイする](how-to-deploy-api.md)」をそれぞれ参照してください。
API キーを作成したら、これを使用量プランに関連付ける必要があります。詳細については、「[API Gateway で REST API の使用量プランを設定する](api-gateway-create-usage-plans.md)」を参照してください。
**注記**
考慮すべきベストプラクティスについては、「[API キーと使用量プランのベストプラクティス](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices)」を参照してください。
**Topics**
+ [
## メソッドで API キーを必須とする
](#api-gateway-usage-plan-configure-apikey-on-method)
+ [
## API キーを作成する
](#api-gateway-usage-plan-create-apikey)
+ [
## API キーをインポートする
](#api-gateway-usage-pan-import-apikey)
## メソッドで API キーを必須とする
次の手順では、API キーを要求する API メソッドを設定する方法について説明します。
------
#### [ AWS マネジメントコンソール ]
**API キーを要求する API メソッドを設定するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. API Gateway のメインナビゲーションペインで、[**Resources (リソース)**] を選択します。
1. [**リソース**] で、新しいメソッドを作成するか、既存のメソッドを選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエスト設定]** で、**[編集]** を選択します。
![\[API キーをメソッドに追加する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png)
1. **[API キーの必要性]** を選択します。
1. **[保存]** を選択します。
1. API をデプロイまたは再デプロイして要件を満たします。
**必要な API キー**のオプションを `false` に設定し、上記の手順を実行しない場合、そのメソッドに対しては API ステージに関連付けられている API キーが使用されません。
------
#### [ AWS CLI ]
次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドは、API キーを要求する `PUT` メソッドを作成します。
```
aws apigateway put-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type "NONE" \
--api-key-required
```
次の [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) コマンドは、既存のメソッドを更新して API キーを要求します。
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/apiKeyRequired",value="true"
```
------
#### [ REST API ]
メソッドの API キーを要求するには、次のいずれかを実行します。
+ [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) を呼び出してメソッドを作成します。リクエストペイロードで `apiKeyRequired` を `true` に設定します。
+ [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) を呼び出して `apiKeyRequired` を `true` に設定します。
------
## API キーを作成する
次の手順で、API キーを作成する方法を示します。API キーをインポートする場合は、このステップをスキップします。
------
#### [ AWS マネジメントコンソール ]
**API キーを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. API Gateway のメインナビゲーションペインで、**[API キー]** を選択します。
1. **[API の作成]** を選択します。
![\[使用量プランの API キーの作成\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png)
1. **[ロール名]** に名前を入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[API キー]** では、**[自動生成]** を選択して API Gateway にキー値を生成させるか、**[カスタム]** を選択して独自のキー値を作成します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html) コマンドは、API キーを作成します。
```
aws apigateway create-api-key \
--name 'Dev API key' \
--description 'API key for Devs' \
--enabled
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) を呼び出して API キーを作成します。
------
## API キーをインポートする
次の手順は、API キーをインポートする方法について説明します。API キーを既に作成している場合は、このステップをスキップします。
------
#### [ AWS マネジメントコンソール ]
**API キーをインポートするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メインナビゲーションペインで、**[API の設定]** を選択します。
1. **[アクション]** ドロップダウンメニューから、**[API キーのインポート]** を選択します。
1. カンマ区切りのキーファイルをロードするには、**[ファイルの選択]** を選択します。テキストエディターにキーを入力します。ファイル形式の詳細については、「[API Gateway API キーファイルの形式](api-key-file-format.md)」を参照してください。
1. 警告が発生した場合、**[警告を失敗とみなす]** を選択してインポートを停止するか、**[警告を無視する]** を選択して、エラーが発生した場合に、有効なキーエントリのインポートを継続します。
1. **[インポート]** を選択して API キーをインポートします。
------
#### [ AWS CLI ]
次の [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html) コマンドは API キーをインポートします。
```
aws apigateway import-api-key \
a--body fileb://keys.csv \
--format csv
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) を呼び出して、ファイルから API キーをインポートします。ファイル形式については、「[API Gateway API キーファイルの形式](api-key-file-format.md)」を参照してください。
------
新しい API キーの値を変更することはできません。API を作成したら、使用量プランを設定します。詳細については、「[API Gateway で REST API の使用量プランを設定する](api-gateway-create-usage-plans.md)」を参照してください。
# API Gateway で REST API の使用量プランを設定する
使用量プランを作成する前に、API キーがセットアップされていることを確認します。詳細については、「[API Gateway で REST API の API キーをセットアップする](api-gateway-setup-api-keys.md)」を参照してください。
**Topics**
+ [
## API をデフォルトの使用量プランに移行する (必要な場合)
](#api-gateway-usage-plan-migrate-to-default)
+ [
## 使用量プランを作成する
](#api-gateway-usage-plan-create)
+ [
## ステージを使用量プランに追加する
](#api-gateway-usage-plan-add-stage)
+ [
## API キーを使用量プランに追加する
](#api-gateway-usage-plan-add-key)
## API をデフォルトの使用量プランに移行する (必要な場合)
使用量プラン機能が展開された 2016 年 8 月 11 日*以降*に API Gateway の使用を開始した場合は、サポートされているすべてのリージョンで自動的に使用量プランが有効になっています。
それ以前に API Gateway の使用を開始した場合は、デフォルトの使用量プランへの移行が必要な場合もあります。選択したリージョンで使用量プランを初めて使用する前に、**使用量プランの有効化**オプションが表示されます。このオプションを有効化すると、既存の API キーに関連付けられた一意の API ステージすべてに、デフォルトの使用量プランが作成されます。デフォルトの使用量プランでは最初にスロットリングやクォータ制限が設定されていません。API キーと API ステージの関連付けは使用量プランにコピーされます。API は以前と同じように動作します。ただし、指定された API ステージの値 (`apiId` および `stage`) を含まれている API キーに関連付ける ([https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html) を使用) には、[ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) `stageKeys` プロパティを使用する代わりに、[https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) `apiStages` プロパティを使用する必要があります。
既にデフォルトの使用量プランに移行しているかどうかを確認するには、[https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html) CLI コマンドを使用します。使用量プランが有効になっている場合は、コマンド出力で `features` リストに `"UsagePlans"` のエントリが含まれます。
次のように AWS CLI を使用して、デフォルトの使用量プランに API を移行することもできます。
**AWS CLI を使用してデフォルトの使用量プランに移行する**
1. この CLI コマンド [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) を呼び出します。
1. `cli-input-json` パラメータには次の JSON を使用します。
```
[
{
"op": "add",
"path": "/features",
"value": "UsagePlans"
}
]
```
## 使用量プランを作成する
次の手順は、使用量プランを作成する方法を説明します。
------
#### [ AWS マネジメントコンソール ]
**使用量プランを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. Amazon API Gateway のメインナビゲーションペインで、**[使用量プラン]** を選択し、次に **[使用量プランの作成]** を選択します。
![\[API 使用量プランのエンティティ\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png)
1. **[ロール名]** に名前を入力します。
1. (オプション) **[説明]** に説明を入力します。
1. デフォルトでは、使用量プランではスロットリングが有効になっています。使用量プランの **[レート]** と **[バースト]** を入力します。**[スロットリング]** を選択してスロットリングをオフにします。
1. デフォルトでは、使用量プランでは一定期間のクォータが有効になっています。**[リクエスト]** には、使用プランの期間中にユーザーが実行できるリクエストの合計数を入力します。**[クォータ]** を選択してクォータを無効にします。
1. **[使用量プランの作成]** を選択します。
------
#### [ AWS CLI ]
次の [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html) コマンドは、月の初めにリセットされる使用量プランを作成します。
```
aws apigateway create-usage-plan \
--name "New Usage Plan" \
--description "A new usage plan" \
--throttle burstLimit=10,rateLimit=5 \
--quota limit=500,offset=0,period=MONTH
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) を呼び出して、使用量プランを作成します。
------
## ステージを使用量プランに追加する
次の手順は、ステージを使用量プランに追加する方法を説明します。
------
#### [ AWS マネジメントコンソール ]
**ステージを使用量プランに追加するには**
1. 使用プランを選択します。
1. **[関連ステージ]** タブの **[ステージを追加する]** を選択します。
![\[API ステージを使用量プランに追加します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png)
1. **[API]** には API を選択します。
1. **[ステージ]** では、ステージを選択します。
1. (オプション) メソッドレベルのスロットリングをオンにするには、次の手順を実行します。
1. **[メソッドレベルのスロットリング]** を選択し、**[メソッドを追加]** を選択します。
1. **[リソース]** では、API からリソースを選択します。
1. **[メソッド]** では、API からメソッドを選択します。
1. 使用量プランの **[レート]** と **[バースト]** を入力します。
1. **[使用量プランに追加]** を選択します。
------
#### [ AWS CLI ]
次の [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) コマンドは、API の `Prod` ステージを使用量プランに追加します。
```
aws apigateway update-usage-plan \
--usage-plan-id abc123 \
--patch-operations op="add",path="/apiStages",value="a1b1c2:Prod"
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) を呼び出して使用量プランを更新します。
------
## API キーを使用量プランに追加する
次の手順は、API キーを使用量プランに追加する方法を示しています。
------
#### [ AWS マネジメントコンソール ]
**使用プランにキーを追加するには**
1. **[関連付けられた API キー]** で、**[API キーを追加]** を選択します。
![\[API 使用量プランのエンティティ\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png)
1.
1. 既存のキーを使用プランに関連付けるには、**[既存のキーを追加]** を選択し、ドロップダウンメニューから既存のキーを選択します。
1. 新しい API キーを作成するには、**[新しいキーを作成して追加]** を選択し、新しいキーを作成します。新しいキーの作成方法の詳細については、「[API キーを作成する](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey)」を参照してください。
1. **[API キーの追加]** を選択します。
------
#### [ AWS CLI ]
次の [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html) コマンドは、既存の API キーを使用量プランに関連付けます。
```
aws apigateway create-usage-plan-key \
--usage-plan-id a1b2c3 \
--key-type "API_KEY" \
--key-id aaa111bbb
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html) を呼び出して、既存の API キーを使用量プランに関連付けます。
API キーをインポートするときに、使用量プランに直接関連付けることもできます。[https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) を呼び出して、指定した使用量プランに 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 つの使用量プランにのみ関連付けることができます。
# API Gateway で REST API の使用プランを維持する
使用量プランのメンテナンスには、特定の期間の使用されたクォータおよび残りのクォータのモニタリング、および、必要に応じて、指定された量の残りのクォータの拡張が含まれます。次の手順は、クォータを監視する方法について説明しています。
------
#### [ AWS マネジメントコンソール ]
**使用されたクォータおよび残りのクォータを監視するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway のメインナビゲーションペインで、**[使用量プラン]** を選択します。
1. 使用プランを選択します。
1. **[関連付けられた API キー]** タブを選択すると、各キーの期間に残っているリクエスト数が表示されます。
1. (オプション) **[使用量データのエクスポート]** を選択し、**[開始]** と **[終了]** を選択します。次に、エクスポートするデータ形式として **[JSON]** または **[CSV]** を選択し、**[エクスポート]** を選択します。
次の例では、エクスポートされたファイルの例を示します。
```
{
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
}
```
この例の使用状況データは、API キー (`px1KW6...qBazOJH`) によって識別される、2016 年 8 月 1 日から 2016 年 8 月 3 日の、API クライアントの毎日の使用状況データです。それぞれの毎日の使用状況データは使用されたクォータおよび残りのクォータを表示します。この例では、サブスクライバは割り当てられたクォータをまだ使用していないため、API 所有者または管理者は残りのクォータを 3 日目に 5000 から 10 に削減しました。
次の手順は、クォータを修正する方法を説明します。
**残りのクォータを拡張するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway のメインナビゲーションペインで、**[使用量プラン]** を選択します。
1. 使用プランを選択します。
1. **[関連付けられた API キー]** タブを選択すると、各キーの期間に残っているリクエスト数が表示されます。
1. API キーを選択し、**[使用期限の延長を付与]** を選択します。
1. **[残りリクエスト]** クォータの数を入力します。使用プランの期間中は、残りのリクエストを増やすことも、残りのリクエストを減らすこともできます。
1. **[クォータの更新]** を選択します。
------
#### [ AWS CLI ]
次の [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) の例では、使用量プランのメソッドレベルのスロットリング設定を追加、削除、または変更します。
**注記**
`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 ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) を呼び出して使用量プランを維持します。
------
# CloudFormation を使用した API キーと使用量プランの作成および設定
CloudFormation を使用して API メソッドで API キーを要求したり、API の使用量プランを作成したりできます。この例の CloudFormation テンプレートでは、次のような処理を実行します。
+ `GET` および `POST` メソッドを使用して API Gateway API を作成します。
+ `GET` および `POST` メソッドの API キーが必要です。この API は、受信する各リクエストの `X-API-KEY` ヘッダーからキーを受け取ります。
+ API キーを作成します。
+ 毎月のクォータを毎月 1,000 リクエスト、スロットリングレート制限を 1 秒あたり 100 リクエスト、スロットリングバースト制限を 1 秒あたり 200 リクエストに指定する使用量プランを作成します。
+ `GET` メソッドに対して、メソッドレベルのスロットリングレート制限を 1 秒あたり 50 リクエストに、メソッドレベルのスロットリングバースト制限を 1 秒あたり 100 リクエストに指定します。
+ 使用量プランに、API ステージと API キーを関連付けます。
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
KeyName:
Type: String
Default: MyKeyName
Description: Name of an API key
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: keys-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
UsagePlan:
Type: AWS::ApiGateway::UsagePlan
DependsOn:
- ApiDeployment
Properties:
Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET
ApiStages:
- ApiId: !Ref Api
Stage: !Sub '${StageName}'
Throttle:
"/pets/GET":
RateLimit: 50.0
BurstLimit: 100
Quota:
Limit: 1000
Period: MONTH
Throttle:
RateLimit: 100.0
BurstLimit: 200
UsagePlanName: "My Usage Plan"
ApiKey:
Type: AWS::ApiGateway::ApiKey
Properties:
Description: API Key
Name: !Sub '${KeyName}'
Enabled: True
UsagePlanKey:
Type: AWS::ApiGateway::UsagePlanKey
Properties:
KeyId: !Ref ApiKey
KeyType: API_KEY
UsagePlanId: !Ref UsagePlan
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# OpenAPI 定義で API キーを使用するようにメソッドを設定する
OpenAPI 定義を使用してメソッドで API キーを要求できます。
メソッドごとに、メソッドを呼び出す API キーを要求するためのセキュリティ要件オブジェクトを作成します。次に、セキュリティ定義で `api_key` を定義します。API キーを作成したら、新しい API ステージを使用量プランに追加します。
次の例では API を作成し、`POST` メソッドと `GET` メソッドで API キーを要求します。
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "2024-03-14T20:20:12Z",
"title" : "keys-api"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/pets" : {
"get" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
},
"post" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
}
}
},
"securityDefinitions" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "keys-api",
"version" : "2024-03-14T20:20:12Z"
},
"servers" : [ {
"url" : "{basePath}",
"variables" : {
"basePath" : {
"default" : "v1"
}
}
} ],
"paths" : {
"/pets" : {
"get" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
},
"post" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
}
}
},
"components" : {
"securitySchemes" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
}
```
------
# API Gateway で REST API の使用量プランをテストする
例として、[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md) で作成される 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` のエラーメッセージが記録されます。ときどき起こるこのようなエラーは無視してかまいません。
# API キーを使用してメソッドを呼び出す
選択した API キーのソースタイプに応じて、以下のいずれかの手順を使用してヘッダーソースの API キー、またはメソッド呼び出しでオーソライザーから返される API キーを使用します。
**ヘッダーソースの API キーを使用するには**
1. 必要な API メソッドで API を作成し、その API をステージにデプロイします。
1. 新しい使用プランを作成するか、既存のものから選択します。デプロイされた API ステージを使用プランに追加します。使用プランに API キーをアタッチするか、プラン内の既存の API キーを選択します。選択した API キーの値を書き留めます。
1. API キーを要求するよう API メソッドをセットアップします。
1. 同じステージに API を再デプロイします。新しいステージに API をデプロイする場合は、必ず新しい API ステージをアタッチするように使用プランを更新します。
1. API キーを使用して API を呼び出します。次の curl コマンドの例は、API キーを使用して API の `prod` ステージの `getUsers` リソースで `GET` メソッドを呼び出します。
```
curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
これでクライアントから、選択した API キーをヘッダー値とする `x-api-key` ヘッダーを指定しながら API メソッドを呼び出すことができるようになりました。呼び出しは以下のようになります。
**オーソライザーソースの API キーを使用するには**
1. 必要な API メソッドで API を作成し、その API をステージにデプロイします。
1. 新しい使用プランを作成するか、既存のものから選択します。デプロイされた API ステージを使用プランに追加します。使用プランに API キーをアタッチするか、プラン内の既存の API キーを選択します。選択した API キーの値を書き留めます。
1. トークンベースの Lambda オーソライザーを作成します。認可レスポンスのルートレベルのプロパティとして `usageIdentifierKey:{api-key}` を含めます。トークンベースのオーソライザーを作成する手順については、「[`TOKEN` オーソライザー Lambda 関数の例](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create)」を参照してください。
1. API キーを要求するように API メソッドを設定し、このメソッドでも Lambda オーソライザーを有効にします。
1. 同じステージに API を再デプロイします。新しいステージに API をデプロイする場合は、必ず新しい API ステージをアタッチするように使用プランを更新します。
これでクライアントから、明示的に API キーを指定せずに、API キーを要求するメソッドを呼び出すことができるようになりました。オーソライザーから返される API キーは自動的に使用されます。