# API Gateway でメソッドリクエストをセットアップする
メソッドリクエストのセットアップするには、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースを作成した後に次のタスクを実行する必要があります。
1. 新しい API を作成するか、既存の API [リソース](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) エンティティを選択する。
1. 新しいまたは選択された API `Resource` の固有の HTTP 動詞になる API [メソッド](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)リソースを作成する。このタスクは、さらに次のサブタスクに分けられます。
+ HTTP メソッドをメソッドリクエストに追加する
+ リクエストパラメータを設定する
+ リクエストボディのモデルを定義する
+ 認可スキームを実行する
+ リクエストの検証を有効化する
これらのタスクは次のメソッドを使用して実行できます。
+ [API Gateway コンソール](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+ AWS CLI コマンド ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) と [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html))
+ AWS SDK 関数 (Node.js の場合は [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) と [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property) など)
+ API Gateway REST API ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) と [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html))
**Topics**
+ [API リソースをセットアップする](#setup-method-resources)
+ [HTTP メソッドをセットアップする](#setup-method-add-http-method)
+ [メソッドリクエストパラメータをセットアップする](#setup-method-request-parameters)
+ [メソッドリクエストモデルをセットアップする](#setup-method-request-model)
+ [メソッドリクエスト認可をセットアップする](#setup-method-request-authorization)
+ [メソッドリクエスト検証をセットアップする](#setup-method-request-validation)
## API リソースをセットアップする
API Gateway API で、API [リソース](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html)エンティティとしてアドレス可能なリソースを階層上部のルートリソース (`/`) とともに公開します。ルートリソースは API のベース URL に関連し、API エンドポイントとステージ名を構成します。API Gateway コンソールで、この基本 URI は **Invoke URI** と呼ばれ、API のデプロイ後に API のステージエディタに表示されます。
API エンドポイントは、デフォルトのホスト名やカスタムドメイン名にすることができます。デフォルトのホスト名は次の形式になります。
```
{api-id}.execute-api.{region}.amazonaws.com
```
この形式で、*\$1api-id\$1* は、API Gateway によって生成された API 識別子を示します。`{region}` 変数は、API 作成時に選択した AWS リージョン (`us-east-1` など) を表します。カスタムドメイン名は、有効のインターネットドメインの下に存在するユーザーが使いやすい任意の名前です。たとえば、`example.com` のインターネットドメインを登録している場合は、あらゆる `*.example.com` がカスタムドメイン名として有効です。詳細については、「[カスタムドメイン名を作成する](how-to-custom-domains.md)」を参照してください。
[PetStore サンプル API](api-gateway-create-api-from-example.md) では、ルートリソース (`/`) がペットストアを公開します。`/pets` リソースは、ペットストアで使用可能なペットのコレクションを表します。`/pets/{petId}` は、指定の識別子 (`petId`) の個別のペットを公開します。`{petId}` のパスパラメータは、リクエストパラメータの一部です。
API リソースをセットアップするには、親として既存のリソースを選択した後、親リソースの下の子リソースを選択します。最初に親となるルートリソースから開始します。この親に子リソースを追加し、その子リソースに新しい親として別のリソースをする手順を親識別子まで繰り返します。その後、名前の付いたリソースを親に追加します。
次の [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) コマンドは、API のすべてのリソースを取得します。
```
aws apigateway get-resources --rest-api-id apiId
```
PetStore サンプル API では、出力は次のようになります。
```
{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}
```
各アイテムは、ルートリソースを除くリソース (`id`) の識別子、直接の親 (`parentId`)、リソース名 (`pathPart`) をリストします。ルートリソースは他と異なり、親を持ちません。親としてリソースを選択した後、次のコマンドを使用して子リソースを追加します。
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id parentId \
--path-part resourceName
```
例えば、PetStore Web サイトで販売するペットフードを追加するには、次のコマンドを使用します。
```
aws apigateway create-resource --rest-api-id a1b2c3 \
--parent-id svzr2028x8 \
--path-part food
```
出力は次のようになります。
```
{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}
```
### プロキシリソースを使用して API セットアップを効率化する
ビジネスの成長に応じて、PetStore のオーナーはフードや玩具などのペット関連のアイテムを商品に追加する場合があります。これをサポートするため、ルートリソースの下に `/food` や `/toys` などのリソースを追加できます。各販売カテゴリの下で、`/food/{type}/{item}` や `/toys/{type}/{item}` などのリソースをさらに追加する必要もあります。この手順には手間がかかる場合があります。ミドルレイヤー `{subtype}` をリソースパスに追加してパス階層を `/food/{type}/{subtype}/{item}` や `/toys/{type}/{subtype}/{item}` などに変更すると、この変更によって既存の API のセットアップは無効になります。これを回避するため、API Gateway [プロキシリソース](api-gateway-set-up-simple-proxy.md)を使用して 1 度にすべての API リソースのセットを公開できます。
API Gateway はプロキシリソースを、リクエストが送信された際に指定されるリクエストのプレースホルダーとして定義しています。プロキシリソースは、greedy パスパラメータと呼ばれることも多い `{proxy+}` の特別なパスパラメータで示されます。`+` マークは、付加されている子リソースを示します。`/parent/{proxy+}` プレースホルダ―は、`/parent/*` のパスパターンに一致するすべてのリソースを表します。greedy パスのパラメータ名には、任意の文字列を使用できます。
次の [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) コマンドは、ルート (`/{proxy+}`) の下にプロキシリソースを作成します。
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id rootResourceId \
--path-part {proxy+}
```
出力は次のようになります。
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}
```
`PetStore` API の例では、`/{proxy+}` を使用して `/pets` と `/pets/{petId}` の両方を表すことができます。このプロキシリソースは、`/food/{type}/{item}` や `/toys/{type}/{item}` または `/food/{type}/{subtype}/{item}` や `/toys/{type}/{subtype}/{item}` など、他のリソース (既存のものや追加されるもの) も参照できます。バックエンド開発者はリソース階層を決定し、クライアント開発者はそれを理解する必要があります。API Gateway は単純に、クライアントがバックエンドに送信したものをすべてパスします。
API のプロキシリソースは、複数の場合があります。例えば、次のプロキシリソースは API 内で許可されます。ただし、`/parent/{proxy+}` は `/parent/{child}/{proxy+}` と同じ親ではないものとします。
```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```
プロキシリソースに非プロキシの兄弟がない場合、兄弟リソースはプロキシリソースの表現から除外されます。前の例では、`/{proxy+}` はルートリソースの下の `/parent[/*]` リソース以外のあらゆるリソースを表します。言い換えると、特定のリソースに対するメソッドリクエストは、リソース階層の同じレベルの一般的なリソースに対するメソッドリクエストより優先されます。
次の表では、API Gateway が API の `prod` ステージの次のリソースにリクエストをルーティングする方法を示しています。
```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```
| リクエスト | 選択されたルート | 説明 |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | リクエストはこのリソースに完全に一致します。 |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | `/pets/{proxy+}` greedy パス変数がこのリクエストを受け取ります。 |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | `/{proxy+}` greedy パス変数がこのリクエストを受け取ります。 |
プロキシリソースは、子リソースを持つことができません。`{proxy+}` の後の API リソースは冗長かつあいまいです。API では次のプロキシリソースは許可されません。
```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```
## HTTP メソッドをセットアップする
API メソッドリクエストは、API Gateway [メソッド](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)リソースに封入されます。メソッドリクエストをセットアップするには、最初に `Method` リソースをインスタンス化し、少なくとも 1 つの HTTP メソッドを設定して、同メソッドに少なくとも 1 つの認可タイプを設定する必要があります。
API Gateway はプロキシリソースに厳密に関連付けられており、`ANY` の HTTP メソッドをサポートします。この `ANY` メソッドは、実行時に指定されるすべての HTTP メソッドを表します。これにより、単一の API メソッドのセットアップを `DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` および `PUT` のサポートされるすべての HTTP メソッドに使用できます。
同様に非プロキシリソースに `ANY` メソッドをセットアップできます。`ANY` メソッドをプロキシリソースと組み合わせることで、API のすべてのリソースに対し、サポートされる HTTP メソッドのための単一の API メソッドのセットアップを使用できます。さらに、バックエンドは既存の API セットアップを無効化することなく進化できます。
API メソッドをセットアップする前に、メソッドを呼び出すことができるユーザーについて考慮します。プランに従って認可タイプを設定します。オープンアクセスの場合は、`NONE` に設定します。IAM アクセス許可を使用するには、認可タイプを`AWS_IAM`に設定します。Lambda オーソライザー関数を使用するには、このプロパティを `CUSTOM` に設定します。Amazon Cognito ユーザープールを使用するには、認可タイプを`COGNITO_USER_POOLS`に設定します。
次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドは、IAM アクセス許可を使用してアクセスを制御する `ANY` 動詞のメソッドリクエストを作成します。
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM
```
別の認可タイプで API メソッドリクエストを作成するには、「[メソッドリクエスト認可をセットアップする](#setup-method-request-authorization)」を参照してください。
## メソッドリクエストパラメータをセットアップする
リクエストパラメータは、クライアントがメソッドリクエストの完了に必要な入力データや実行コンテクストを提供する方法の 1 つです。メソッドパラメータは、パスパラメータ、ヘッダー、クエリ文字列パラメータにできます。メソッドリクエストのセットアップの一環として、必要なリクエストパラメータを宣言し、クライアントが使用できるようにする必要があります。非プロキシ統合では、これらのリクエストパラメータをバックエンド要件に適合する形式に変換できます。
たとえば、`GET /pets/{petId}` メソッドリクエストでは `{petId}` パス変数は必須リクエストパラメータです。このパスパラメータは、`put-method` の AWS CLI コマンドを呼び出す際に宣言できます。次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドは、パスのパラメータを必須とするメソッドを作成します。
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.path.petId=true
```
必須ではないパラメータは、`false` で `request-parameters` に設定できます。例えば、`GET /pets` メソッドで `type` のオプションのクエリ文字列パラメータと `age` のオプションのヘッダーパラメータを使用する場合は、次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドを使用してそれらのパラメータを宣言できます。
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.type=false,method.request.header.age=false
```
この省略形式の代わりに、JSON 文字列を使用して `request-parameters` 値を設定できます。
```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```
このようにセットアップすると、クライアントはペットをタイプ別にクエリできます。
```
GET /pets?type=dog
```
その後、クライアントは次のように子犬である犬を求めてクエリを実行できます。
```
GET /pets?type=dog
age:puppy
```
メソッドリクエストパラメータを統合リクエストパラメータにマッピングする方法の詳細については、「[API Gateway での REST API の統合](how-to-integration-settings.md)」を参照してください。
## メソッドリクエストモデルをセットアップする
ペイロードに入力データを取ることができる API メソッドでは、モデルを使用できます。モデルは [JSON スキーマのドラフト 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) で表され、リクエストボディのデータ構造を説明します。モデルにより、クライアントは入力としてメソッドリクエストペイロードを作成する方法を決定できます。さらに重要なことに、API Gateway はモデルを使用し、API Gateway コンソールで統合をセットアップするために[リクエストを検証し](api-gateway-method-request-validation.md)、[SDK を作成し](how-to-generate-sdk.md)、マッピングテンプレートを初期化します。[モデル](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)の作成方法については、「[データモデルを理解する](models-mappings-models.md)」を参照してください。
メソッドペイロードはコンテンツタイプに応じて異なる形式になる場合があります。モデルは適用されたペイロードのメディアタイプに対してインデックス作成されます。API Gateway は、`Content-Type` リクエストヘッダーを使用してコンテンツタイプを決定します。メソッドリクエストモデルをセットアップするには、`"media-type":"model-name"` `requestModels` コマンドを呼び出す際に AWS CLI 形式のキー値のペアを `put-method` マップに追加します。
コンテンツタイプに関係なく同じモデルを使用するには、キーとして `$default` を指定します。
例えば、PetStore サンプル API の `POST /pets` メソッドリクエストの JSON ペイロードにモデルを設定するには、次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドを使用できます。
```
aws apigateway put-method \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--request-models '{"application/json":"petModel"}'
```
ここで `petModel` は、ペットを説明する [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) リソースの `Model` プロパティ値です。実際のスキーマ定義は、`schema` リソースの [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) プロパティの JSON 文字列値として表されます。
Java または厳密に型指定された API のその他の SDK では、入力データはスキーマ定義から取得された `petModel` クラスとしてキャストされます。リクエストモデルを使用すると、作成された SDK 内の入力データは、デフォルトの `Empty` モデルから取得された `Empty` クラスにキャストされます。この場合、クライアントは正しいデータクラスをインスタンス化して必要な入力を提供することができません。
## メソッドリクエスト認可をセットアップする
API メソッドを呼び出すことができるユーザーを制御するため、メソッドの [[認可タイプ](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)] を設定できます。このタイプを使用し、IAM ロールとポリシー (`AWS_IAM`)、Amazon Cognito ユーザープール (`COGNITO_USER_POOLS`)、Lambda オーソライザー (`CUSTOM`) など、サポートされているオーソライザーのいずれかを有効にできます。
API メソッドへのアクセスを認可する IAM アクセス許可を使用するには、`authorization-type` 入力プロパティを **AWS\$1IAM** に設定します。このオプションを設定すると、API Gateway は、発信者の証明情報に基づいて、リクエストにある発信者の署名を検証します。検証されたユーザーにメソッドを呼び出す権限がある場合、リクエストは承諾されます。それ以外の場合、リクエストは拒否され、発信者は未承認エラーレスポンスを受信します。発信者に API メソッドを呼び出す権限がない限り、メソッドの呼び出しは成功しません。以下の IAM ポリシーでは、同じ AWS アカウント 内で作成されたすべての API メソッドを呼び出す権限を発信者に付与します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]
}
```
------
詳細については、「[IAM アクセス許可を使用して REST API へのアクセスを制御する](permissions.md)」を参照してください。
現在、このポリシーは API 所有者の AWS アカウント 内のユーザー、グループ、ロールにのみ付与できます。別の AWS アカウント のユーザーは、`execute-api:Invoke` アクションを呼び出すために必要なアクセス許可がある API 所有者の AWS アカウント 内のロールを引き受けることが許可されている場合のみ、API メソッドを呼び出すことができます。クロスアカウントアクセス許可の詳細については、「[IAM ロールの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)」を参照してください。
AWS CLI や AWS SDK を使用するか、[Signature Version 4 (SigV4) 署名](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html)を実装する [Postman](https://www.postman.com/) などの REST API クライアントを使用できます。
Lambda オーソライザーを使用して API メソッドへのアクセスを承認するには、`authorization-type` 入力プロパティを `CUSTOM` に設定し、[https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 入力プロパティを既存の Lambda オーソライザーの [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) プロパティ値に設定します。参照された Lambda オーソライザーは、`TOKEN` または `REQUEST` タイプになります。Lambda オーソライザーの作成については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。
Amazon Cognito ユーザープールを使用して API メソッドへのアクセスを承認するには、`authorization-type` 入力プロパティを `COGNITO_USER_POOLS` に設定し、[https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 入力プロパティを作成済みの `COGNITO_USER_POOLS` オーソライザーの [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) プロパティ値に設定します。Amazon Cognito ユーザープールオーソライザーの詳細な作成方法については、「[Amazon Cognito ユーザープールをオーソライザーとして使用して REST API へのアクセスを制御する](apigateway-integrate-with-cognito.md)」を参照してください。
## メソッドリクエスト検証をセットアップする
API メソッドリクエストをセットアップする際は、リクエスト検証を有効化できます。最初に[リクエストバリデーター](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)を作成する必要があります。次の [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) コマンドは、本文のみを検証するリクエストバリデーターを作成します。
```
aws apigateway create-request-validator \
--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters
```
出力は次のようになります。
```
{
"validateRequestParameters": false,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}
```
このリクエストバリデーターにより、メソッドリクエストの設定の一部としてリクエストの検証を使用できます。次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドは、受信リクエスト本文が `PetModel` と一致する必要があり、2 つのリクエストパラメータを必須としないメソッドリクエストを作成します。
```
aws apigateway put-method \
--rest-api-id 7zw9uyk9kl \
--resource-id xdsvhp \
--http-method PUT \
--authorization-type "NONE" \
--request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \
--request-models '{"application/json":"petModel"}' \
--request-validator-id jgpyy6
```
リクエストの検証にリクエストパラメータを含めるには、リクエストバリデーターで `validateRequestParameters` を `true` に設定し、`put-method` コマンドで特定のリクエストパラメータを `true` に設定する必要があります。