API Gateway でメソッドリクエストをセットアップする
メソッドリクエストのセットアップするには、RestApi リソースを作成した後に次のタスクを実行する必要があります。
これらのタスクは次のメソッドを使用して実行できます。
-
AWS CLI コマンド (create-resource と put-method)
-
AWS SDK 関数 (Node.js の場合は createResource と putMethod など)
-
API Gateway REST API (resource:create と method:put)
トピック
API リソースをセットアップする
API Gateway API で、API リソースエンティティとしてアドレス可能なリソースを階層上部のルートリソース (/
) とともに公開します。ルートリソースは API のベース URL に関連し、API エンドポイントとステージ名を構成します。API Gateway コンソールで、この基本 URI は Invoke URI と呼ばれ、API のデプロイ後に API のステージエディタに表示されます。
API エンドポイントは、デフォルトのホスト名やカスタムドメイン名にすることができます。デフォルトのホスト名は次の形式になります。
{api-id}
.execute-api.{region}
.amazonaws.com
この形式で、{api-id}
は、API Gateway によって生成された API 識別子を示します。
変数は、API 作成時に選択した AWS リージョン ({region}
us-east-1
など) を表します。カスタムドメイン名は、有効のインターネットドメインの下に存在するユーザーが使いやすい任意の名前です。たとえば、example.com
のインターネットドメインを登録している場合は、あらゆる *.example.com
がカスタムドメイン名として有効です。詳細については、「カスタムドメイン名を作成する」を参照してください。
PetStore サンプル API では、ルートリソース (/
) がペットストアを公開します。/pets
リソースは、ペットストアで使用可能なペットのコレクションを表します。/pets/{petId}
は、指定の識別子 (petId
) の個別のペットを公開します。{petId}
のパスパラメータは、リクエストパラメータの一部です。
API リソースをセットアップするには、親として既存のリソースを選択した後、親リソースの下の子リソースを選択します。最初に親となるルートリソースから開始します。この親に子リソースを追加し、その子リソースに新しい親として別のリソースをする手順を親識別子まで繰り返します。その後、名前の付いたリソースを親に追加します。
AWS CLI により、get-resources
コマンドを呼び出し、API のどのリソースが使用可能かを調べることができます。
aws apigateway get-resources --rest-api-id
<apiId>
\ --region<region>
結果として、API の現在使用可能なリソースのリストが返されます。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>
\ --region<region>
\ --parent-id<parentId>
\ --path-part<resourceName>
たとえば、PetStore ウェブサイトの商品にペットフードを追加するには、food
を path-part
に、food
を parent-id
に設定し、svzr2028x8
リソースをルート (/) に追加します。結果は次のようになります。
{ "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 プロキシリソースを使用して 1 度にすべての API リソースのセットを公開できます。
API Gateway はプロキシリソースを、リクエストが送信された際に指定されるリクエストのプレースホルダーとして定義しています。プロキシリソースは、greedy パスパラメータと呼ばれることも多い {proxy+}
の特別なパスパラメータで示されます。+
マークは、付加されている子リソースを示します。/parent/{proxy+}
プレースホルダ―は、/parent/*
のパスパターンに一致するすべてのリソースを表します。greedy パスパラメータの名前である proxy
は、通常のパスパラメータ名を扱うのと同じ方法で、別の文字列で置き換えることができます。
AWS CLI を使用して次のコマンドを呼び出し、ルート (/{proxy+}
) の下に次のプロキシリソースをセットアップできます。
aws apigateway create-resource --rest-api-id
<apiId>
\ --region<region>
\ --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 内で次のプロキシリソースが許可されます。
/{proxy+} /parent/{proxy+} /parent/{child}/{proxy+}
プロキシリソースに非プロキシの兄弟がない場合、兄弟リソースはプロキシリソースの表現から除外されます。前の例では、/{proxy+}
はルートリソースの下の /parent[/*]
リソース以外のあらゆるリソースを表します。言い換えると、特定のリソースに対するメソッドリクエストは、リソース階層の同じレベルの一般的なリソースに対するメソッドリクエストより優先されます。
プロキシリソースは、子リソースを持つことができません。{proxy+}
の後の API リソースは冗長かつあいまいです。API では次のプロキシリソースは許可されません。
/{proxy+}/child /parent/{proxy+}/{child} /parent/{child}/{proxy+}/{grandchild+}
HTTP メソッドをセットアップする
API メソッドリクエストは、API Gateway メソッドリソースに封入されます。メソッドリクエストをセットアップするには、最初に Method
リソースをインスタンス化し、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
に設定します。
次の AWS CLI コマンドは、指定されたリソース (6sxz2j
) のアクセスの制御に IAM 許可を使用して、このリソースに対する ANY
動詞のメソッドリクエストを作成する方法を示しています。
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM \ --region us-west-2
別の認証タイプで API メソッドリクエストを作成するには、「メソッドリクエスト認証をセットアップする」を参照してください。
メソッドリクエストパラメータをセットアップする
リクエストパラメータは、クライアントがメソッドリクエストの完了に必要な入力データや実行コンテクストを提供する方法の 1 つです。メソッドパラメータは、パスパラメータ、ヘッダー、クエリ文字列パラメータにできます。メソッドリクエストのセットアップの一環として、必要なリクエストパラメータを宣言し、クライアントが使用できるようにする必要があります。非プロキシ統合では、これらのリクエストパラメータをバックエンド要件に適合する形式に変換できます。
たとえば、GET /pets/{petId}
メソッドリクエストでは {petId}
パス変数は必須リクエストパラメータです。このパスパラメータは、AWS CLI の put-method
コマンドを呼び出す際に宣言できます。次の図に説明を示します。
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --region us-west-2 \ --request-parameters method.request.path.petId=true
必須ではないパラメータは、false
で request-parameters
に設定できます。たとえば、GET /pets
メソッドが type
のオプションクエリ文字列パラメータと breed
のオプションヘッダーパラメータを使用する場合、/pets
リソースの id
が 6sxz2j
であることを前提として、次の CLI コマンドを使用してこれらを宣言できます。
aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --region us-west-2 \ --request-parameters method.request.querystring.type=false,method.request.header.breed=false
この省略形式の代わりに、JSON 文字列を使用して request-parameters
値を設定できます。
'{"method.request.querystring.type":false,"method.request.header.breed":false}'
このようにセットアップすると、クライアントはペットをタイプ別にクエリできます。
GET /pets?type=dog
さらに、クライアントは次のようにプードル種の犬をクエリできます。
GET /pets?type=dog breed:poodle
メソッドリクエストパラメータを統合リクエストパラメータにマッピングする方法の詳細については、「API Gateway での REST API の統合」を参照してください。
メソッドリクエストモデルをセットアップする
ペイロードに入力データを取ることができる API メソッドでは、モデルを使用できます。モデルは JSON スキーマのドラフト 4
メソッドペイロードはコンテンツタイプに応じて異なる形式になる場合があります。モデルは適用されたペイロードのメディアタイプに対してインデックス作成されます。API Gateway は、Content-Type
リクエストヘッダーを使用してコンテンツタイプを決定します。メソッドリクエストモデルをセットアップするには、AWS CLI put-method
コマンドを呼び出す際に "
形式のキー値のペアを <media-type>
":"<model-name>
"requestModels
マップに追加します。
コンテンツタイプに関係なく同じモデルを使用するには、キーとして $default
を指定します。
たとえば、PetStore サンプル API の POST /pets
メソッドリクエストの JSON ペイロードにモデルを設定するため、次の AWS CLI コマンドを呼び出すことができます。
aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --region us-west-2 \ --request-models '{"application/json":"petModel"}'
ここで petModel
は、ペットを説明する name
リソースの Model
プロパティ値です。実際のスキーマ定義は、schema
リソースの Model
プロパティの JSON 文字列値として表されます。
Java または厳密に型指定された API のその他の SDK では、入力データはスキーマ定義から取得された petModel
クラスとしてキャストされます。リクエストモデルを使用すると、作成された SDK 内の入力データは、デフォルトの Empty
モデルから取得された Empty
クラスにキャストされます。この場合、クライアントは正しいデータクラスをインスタンス化して必要な入力を提供することができません。
メソッドリクエスト認証をセットアップする
API メソッドを呼び出すことができるユーザーを制御するため、メソッドの認証タイプを設定できます。このタイプを使用し、IAM ロールとポリシー (AWS_IAM
)、Amazon Cognito ユーザープール (COGNITO_USER_POOLS
)、Lambda オーソライザー (CUSTOM
) など、サポートされているオーソライザーのいずれかを有効にできます。
API メソッドへのアクセスを認証する IAM アクセス許可を使用するには、authorization-type
への AWS_IAM
入力プロパティを設定します。このオプションを設定すると、API Gateway は、発信者の証明情報に基づいて、リクエストにある発信者の署名を検証します。検証されたユーザーにメソッドを呼び出す権限がある場合、リクエストは承諾されます。それ以外の場合、リクエストは拒否され、発信者は未承認エラーレスポンスを受信します。発信者に API メソッドを呼び出す権限がない限り、メソッドの呼び出しは成功しません。以下の IAM ポリシーでは、同じ AWS アカウント 内で作成されたすべての API メソッドを呼び出す権限を発信者に付与します。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": "arn:aws:execute-api:*:*:*" } ] }
詳細については、「IAM アクセス許可を使用して REST API へのアクセスを制御する」を参照してください。
現在、このポリシーは API 所有者の AWS アカウント 内のユーザー、グループ、ロールにのみ付与できます。別の AWS アカウント のユーザーは、execute-api:Invoke
アクションを呼び出すために必要なアクセス許可がある API 所有者の AWS アカウント 内のロールを引き受けることが許可されている場合のみ、API メソッドを呼び出すことができます。クロスアカウントアクセス許可の詳細については、「IAM ロールの使用」を参照してください。
AWS CLI や AWS SDK を使用するか、Signature Version 4 (SigV4) 署名を実装する Postman
Lambda オーソライザーを使用して API メソッドへのアクセスを承認するには、authorization-type
入力プロパティを CUSTOM
に設定し、authorizer-id
入力プロパティを既存の Lambda オーソライザーの id
プロパティ値に設定します。参照された Lambda オーソライザーは、TOKEN
または REQUEST
タイプになります。Lambda オーソライザーの作成については、「API Gateway Lambda オーソライザーを使用する」を参照してください。
Amazon Cognito ユーザープールを使用して API メソッドへのアクセスを承認するには、authorization-type
入力プロパティを COGNITO_USER_POOLS
に設定し、authorizer-id
入力プロパティを作成済みの COGNITO_USER_POOLS
オーソライザーの id
プロパティ値に設定します。Amazon Cognito ユーザープールオーソライザーの詳細な作成方法については、「Amazon Cognito ユーザープールをオーソライザーとして使用して REST API へのアクセスを制御する」を参照してください。
メソッドリクエスト検証をセットアップする
API メソッドリクエストをセットアップする際は、リクエスト検証を有効化できます。最初にリクエストバリデーターを作成する必要があります。
aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters
この CLI コマンドは、本文のみのリクエストバリデーターを作成します。次に出力例を示します。
{ "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" }
このリクエストバリデーターでは、メソッドリクエストのセットアップの一環として、リクエスト検証を有効化できます。
aws apigateway put-method \ --rest-api-id 7zw9uyk9kl --region us-west-2 --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
リクエスト検証に含まれたリクエストパラメータは、必須として宣言される必要があります。ページのクエリ文字列パラメータがリクエスト検証に使用されている場合、前の例の request-parameters
マップは '{"method.request.querystring.type": false,
"method.request.querystring.page":true}'
として指定される必要があります。