API Gateway でメソッドリクエストをセットアップする - Amazon API Gateway
API リソースをセットアップするHTTP メソッドをセットアップするメソッドリクエストパラメータをセットアップするメソッドリクエストモデルをセットアップするメソッドリクエスト認可をセットアップするメソッドリクエスト検証をセットアップする

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

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

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

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

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

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

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

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

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

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

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 識別子を示します。{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 ウェブサイトの商品にペットフードを追加するには、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 内で許可されます。ただし、/parent/{proxy+} は /parent/{child}/{proxy+} と同じ親ではないものとします。

/{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 リソースをインスタンス化し、少なくとも 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に設定します。

次の 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 はモデルを使用し、API Gateway コンソールで統合をセットアップするためにリクエストを検証し、SDK を作成し、マッピングテンプレートを初期化します。モデルの作成方法については、「データモデルを理解する」を参照してください。

メソッドペイロードはコンテンツタイプに応じて異なる形式になる場合があります。モデルは適用されたペイロードのメディアタイプに対してインデックス作成されます。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 などの 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": 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}' として指定される必要があります。