Amazon API Gateway
開発者ガイド

API Gateway のメソッドリクエストをセットアップする

メソッドリクエストのセットアップするには、RestApi リソースを作成した後に次のタスクを実行する必要があります。

  1. 新しい API を作成するか、既存の API リソース エンティティを選択する。

  2. 新しいまたは選択された API Resource の固有の HTTP 動詞になる API メソッド リソースを作成する。このタスクは、さらに次のサブタスクに分けられます。

    • HTTP メソッドをメソッドリクエストに追加する

    • リクエストパラメーターを設定する

    • リクエストボディのモデルを定義する

    • 認証スキームを実行する

    • リクエストの検証を有効化する

これらのタスクは次のメソッドを使用して実行できます。

これらのツールの使用例については、「 API Gateway の REST API セットアップを初期化する」を参照してください。

API リソースをセットアップする

API Gateway API で、API リソースエンティティとしてアドレス可能なリソースを階層上部のルートリソース (/) とともに公開します。ルートリソースは API のベース URL に関連し、API エンドポイントとステージ名を構成します。API Gateway コンソールで、この基本 URI は [呼び出し URI] と呼ばれ、API のデプロイ後に API のステージエディタに表示されます。

API エンドポイントは、デフォルトのホスト名やカスタムドメイン名にすることができます。デフォルトのホスト名は次の形式になります。

{api-id}.execute-api.{region}.amazonaws.com

この形式で、{api-id} は、API Gateway に生成された API 識別子を示します。{region} 変数は、API 作成時に選択した AWS リージョン (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 ウェブサイトの商品にペットフードを追加するには、foodpath-part に、foodparent-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 メソッドのセットアップを DELETEGETHEADOPTIONSPATCHPOST および PUT のサポートされるすべての HTTP メソッドに使用できます。

同様に非プロキシリソースに ANY メソッドをセットアップできます。ANY メソッドをプロキシリソースと組み合わせることで、API のすべてのリソースに対し、サポートされる HTTP メソッドのための単一の API メソッドのセットアップを使用できます。さらに、バックエンドは既存の API セットアップを無効化することなく進化できます。

API メソッドをセットアップする前に、メソッドを呼び出すことができるユーザーについて考慮します。プランに従って認証タイプを設定します。オープンアクセスの場合は、NONE に設定します。IAM 権限を使用するには、認証タイプを AWS_IAM に設定します。Lambda 関数に基づいた 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

必須ではないパラメーターは、falserequest-parameters に設定できます。たとえば、GET /pets メソッドが type のオプションクエリ文字列パラメーターと breed のオプションヘッダーパラメーターを使用する場合、/pets リソースの id6sxz2j であることを前提として、次の 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 はモデルを使用し、API Gateway コンソールで統合をセットアップするためにリクエストを検証し、SDK を作成して、マッピングテンプレートを初期化します。モデルを作成する方法の詳細については、「モデルとマッピングテンプレート」を参照してください。

メソッドペイロードはコンテンツタイプに応じて異なる形式になる場合があります。モデルは適用されrたペイロードのメディアタイプに対してインデックス作成されます。メソッドリクエストモデルをセットアップするには、AWS CLI put-method コマンドを呼び出す際に "<media-type>":"<model-name>" 形式のキー値のペアを requestModels マップに追加します。

たとえば、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 は、ペットを説明する Model リソースの name プロパティ値です。実際のスキーマ定義は、Model リソースの schema プロパティの JSON 文字列値として表されます。

Java または厳密に型指定された API のその他の SDK では、入力データはスキーマ定義から取得された petModel クラスとしてキャストされます。リクエストモデルを使用すると、作成された SDK 内の入力データは、デフォルトの Empty モデルから取得された Empty クラスにキャストされます。この場合、クライアントは正しいデータクラスをインスタンス化して必要な入力を提供することができません。

メソッドリクエスト認証をセットアップする

API メソッドを呼び出すことができるユーザーを制御するため、メソッドの認証タイプを設定できます。このタイプを使用し、IAM ロールとポリシー (AWS_IAM)、Amazon Cognito ユーザープール (COGNITO_USER_POOLS)、Lambda 関数に基づく Lambda オーソライザー (CUSTOM) など、サポートされているオーソライザーのいずれかを有効にできます。API Gateway コンソールは、デフォルトでオープンアクセスに NONE を設定します。

API メソッドへのアクセスを認証する IAM 権限を使用するには、AWS_IAM への authorization-type 入力プロパティを設定します。このオプションが設定されると、API Gateway は、発信者の IAM ユーザーのアクセスキー識別子とシークレットキーに基づいて、リクエストにある発信者の署名を検証します。検証されたユーザーがメソッドを呼び出す権限を持つ場合、リクエストは承諾されます。それ以外の場合、リクエストは拒否され、発信者は未承認エラーレスポンスを受信します。メソッドの呼び出しは、API メソッドを呼び出す権限が発信者に与えられているか、権限を与えられたロールを発信者が割り当てることができない限り、成功しません。IAM ユーザーに次の IAM ポリシーがアタッチされている発信者は、この API メソッドに加え、同一の AWS アカウントの任意のユーザーによって作成された他の API メソッドを呼び出す権限を持ちます。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": "arn:aws:execute-api:*:*:*" } ] }

詳細については、「IAM アクセス権限により API へのアクセスを制御する」を参照してください。

現時点で、このポリシーは API オーナーのアカウントの IAM ユーザーにのみ付与することができます。別の AWS アカウントのユーザーは、API オーナーアカウントのロールを割り当てることができ、割り当てられたロールが execute-api:Invoke アクションに適した権限を持つ場合、API メソッドを呼び出すことができます。クロスアカウント権限の詳細については、「IAM ロールの使用」を参照してください。

署名バージョン 4 の署名を実装する Postman など、AWS CLI、AWS SDK、または REST API クライアントを使用できます。

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": true, "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}' として指定される必要があります。