メニュー
Amazon API Gateway
開発者ガイド

API Gateway プロキシ統合のセットアップ

API Gateway API のプロキシリソースにプロキシ統合を設定するには、次の 3 つのタスクを実行します。

  • greedy パス変数 {proxy+} を使用してプロキシリソースを作成します。

  • プロキシリソースに ANY メソッドを設定します。

  • HTTP または Lambda 統合タイプを使用してリソースおよびメソッドをバックエンドに統合します。

注記

greedy パス変数、ANY メソッド、およびプロキシ統合タイプは、よく一緒に使用されますが独立した機能です。特定の HTTP メソッドを greedy リソースに設定することも、プロキシ以外の統合タイプをプロキシリソースに適用することもできます。

API Gateway は、Lambda プロキシ統合または HTTP プロキシ統合を使用した処理方法に一定の制約と制限を設定しています。詳細については、「既知の問題」を参照してください。

注記

パススルーによるプロキシの統合を使用するため、ペイロードのコンテンツタイプが指定されない場合、API Gateway はデフォルトの Content-Type:application/json ヘッダーを返します。

API Gateway プロキシリソース

API Gateway はプロキシリソースを、リクエストが提出された際に指定されるリクエストのプレースホルダーとして定義しています。API Gateway プロキシリソースには次のプロパティがあります。

  • {proxy+} として示される特別なパスパラメーター。このパスパラメーターは、API の親リソースの下位にある子リソースを表します。つまり、/parent/{proxy+} は、/parent/* というパスパターンに一致するあらゆるリソースを表すことができます。+ 記号は、一致したリソースに対するすべてのリクエストをインターセプトすることを API Gateway に指示します。この特別なパスパラメーターは、greedy パス変数とも呼ばれます。proxy 変数は greedy パス変数の名前であり、通常のパスパラメーター名を扱いのと同じ方法で、別の文字列で置き換えることができます。

  • ANY という名前の特別なメソッドは、サポートされているすべてのメソッド (DELETEGETHEADOPTIONSPATCHPOSTPUT) に対して設定したのと同じ統合を定義する目的に使用されます。

API メソッドは、API のリソース階層の同一レベルでプロキシリソースと非プロキシリソース上で定義できます。たとえば、GET メソッドを、API のルートリソース (/) 下にある /{ggg+} および /sss に公開することができます。クライアントが GET /aaa を呼び出し、aaa が「sss」以外のリソース名である場合、呼び出しはプロキシ統合とともに GET /{ggg+} を通過します。言い換えると、API Gateway では特定のリソースに対する各メソッドリクエストは、リソース階層の同じレベルの一般的なリソースに対する同様のメソッドリクエストより優先されます。

API Gateway プロキシ統合のタイプ

以下の 2 つのプロキシ統合タイプのいずれかを使用して プロキシリソース をバックエンドと統合することで、もっとも高機能になります。

  • API Gateway REST API の HTTP_PROXY によって指定される HTTP プロキシ統合は、メソッドリクエストをバックエンドの HTTP エンドポイントと統合するために使用します。この統合タイプでは、API Gateway は、一定の制約と制限に従って、フロントエンドとバックエンド間でリクエストとレスポンスの全体を単純に渡します。

  • API Gateway REST API の AWS_PROXY によって指定される Lambda プロキシ統合は、メソッドリクエストをバックエンドの Lambda 関数と統合するために使用します。この統合タイプでは、API Gateway はデフォルトのマッピングテンプレートを適用してリクエスト全体を Lambda 関数に送信し、Lambda 関数の出力を HTTP レスポンスに変換します。

HTTP プロキシ統合をプロキシリソースに適用するときは、単一の統合セットアップを使用して、HTTP バックエンドのエンドポイント階層の一部または全体を公開するように API を設定できます。たとえば、バックエンドのウェブサイトがルートノード (/site) からツリーノードで複数のブランチとして編成されているとします (/site/a0/a1/.../aN/site/b0/b1/.../bM など)。/site/{proxy} の URL パスを使用して /api/{proxy+} の プロキシリソースで ANY メソッドをバックエンドのエンドポイントと統合した場合、単一の統合リクエストで[a0, a1, ..., aN, b0, b1, ...bM, ...] のどれに対しても任意の HTTP オペレーション (GET、POST など) をサポートできます。特定の HTTP メソッド (GET など) にプロキシ統合を適用した場合、結果の統合リクエストは、それらの任意のバックエンドノードに対して指定した (GET などの) オペレーションで有効です。

同様に、Lambda プロキシ統合を /api/{proxy+} のプロキシリソースに適用して単一の統合を設定し、バックエンドの Lambda 関数を /api の下位にある任意の API リソースでの変更に個別に対応させることができます。

プロキシリソースに HTTP プロキシ統合をセットアップする

プロキシリソースに HTTP プロキシ統合タイプをセットアップするには、greedy パスパラメータ (/parent/{proxy+} など) を使用して API リソースを作成し、このリソースを ANY メソッドで HTTP バックエンドのエンドポイント (https://petstore-demo-endpoint.execute-api.com/petstore/{proxy} など) と統合します。greedy パスパラメーターは、リソースパスの末尾にある必要があります。

非プロキシリソースと同様に、API Gateway コンソールを使用するか、Swagger 定義ファイルをインポートするか、API Gateway REST API を直接呼び出すことによって、プロキシリソースに HTTP プロキシ統合をセットアップできます。API Gateway コンソールを使用してプロキシリソースに HTTP 統合を設定する詳しい手順については、「HTTP プロキシ統合で API をビルドする 」を参照してください。

以下の Swagger API 定義ファイルは、PetStore ウェブサイトに統合された API とプロキシリソースの例を示しています。

Copy
{ "swagger": "2.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } } }

この例では、キャッシュのキーは、プロキシリソースの method.request.path.proxy パスパラメーターで宣言されます。これにより、API Gateway コンソールを使用して API を作成するときのデフォルト設定です。API ベースパス (/test、ステージに対応) はウェブサイトの PetStore ページ (/petstore) にマッピングされます。単一の統合リクエストは、API の greedy パス変数とキャッチオールの ANY メソッドを使用して、PetStore ウェブサイト全体をミラーリング処理します。以下の例に、このミラーリングを示しています。

  • ANYGET{proxy+}pets に設定

    フロントエンドから開始されたメソッドリクエスト:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

    バックエンドに送信された統合リクエスト:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

    ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返されたペットの最初のバッチが含まれるペイロードを返します。

  • ANYGET{proxy+}pets?type=dog に設定

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1

    バックエンドに送信された統合リクエスト:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1

    ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された特定の犬の最初のバッチが含まれるペイロードを返します。

  • ANYGET{proxy+}pets/{petId} に設定

    フロントエンドから開始されたメソッドリクエスト:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1

    バックエンドに送信された統合リクエスト:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1

    ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された特定のペットが含まれるペイロードを返します。

  • ANYPOST{proxy+}pets に設定

    フロントエンドから開始されたメソッドリクエスト:

    Copy
    POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    バックエンドに送信された統合リクエスト:

    Copy
    POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された新しく作成したペットが含まれるペイロードを返します。

  • ANYGET{proxy+}pets/cat に設定

    フロントエンドから開始されたメソッドリクエスト:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat

    バックエンドに送信された統合リクエスト:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat

    プロキシリソースパスの実行時インスタンスが、バックエンドのエンドポイントに対応しておらず、結果としいて生成されるリクエストは無効です。その結果、400 Bad Request レスポンスが次のエラーメッセージとともに返されます。

    Copy
    { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] }
  • ANYGET{proxy+}null に設定

    フロントエンドから開始されたメソッドリクエスト:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test

    バックエンドに送信された統合リクエスト:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore

    対象のリソースはプロキシリソースの親ですが、ANY メソッドを実行時インスタンスは、そのリソースの API に定義されていません。その結果、この GET リクエストは、403 Forbidden レスポンスと、API Gateway から返された "認証トークンが見つからない" エラーを返します。API が親リソース (/) で GET または ANY メソッドを公開している場合、呼び出しからは 404 Not Found レスポンスと、バックエンドから返された Cannot GET /petstore メッセージが返されます。

クライアントリクエストの場合、対象のエンドポイント URL が無効であるか、HTTP 動詞が有効であってもサポートされていない場合、ベック遠渡は 404 Not Found レスポンスを返します。サポートされていない HTTP メソッドの場合は、403 Forbidden レスポンスが返されます。

プロキシリソースに Lambda プロキシ統合をセットアップする

プロキシリソース に Lambda プロキシ統合タイプをセットアップするには、greedy パスパラメータ (/parent/{proxy+} など) を使用して API リソースを作成し、このリソースを ANY メソッドで Lambda 関数のバックエンド (arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource など) と統合します。greedy パスパラメーターは、API リソースパスの末尾にある必要があります。プロキシ以外のリソースと同様に、API Gateway コンソールを使用するか、Swagger 定義ファイルをインポートするか、API Gateway REST API を直接呼び出すことによって、プロキシリソースをセットアップできます。

API Gateway コンソールを使用してプロキシリソースに Lambda プロキシ統合を設定する詳しい手順については、「API Gateway コンソールを使用して Lambda プロキシ統合で API Gateway API をビルドする」を参照してください。

以下の Swagger API 定義ファイルは、SimpleLambda4ProxyResource Lambda 関数を使用して統合された API とプロキシリソースの例を示しています。

Copy
{ "swagger": "2.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "basePath": "/testStage", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } } }

Lambda プロキシ統合を使用すると、実行時に、API Gateway は受信リクエストを Lambda 関数の入力 event パラメーターにマッピングします。入力にはリクエストメソッド、パス、ヘッダー、クエリパラメーター、ペイロード、関連コンテキスト、定義済みステージ変数が含まれています。入力形式については「プロキシ統合のための Lambda 関数の入力形式 」で説明しています。API Gateway が Lambda 出力を HTTP レスポンスに正常にマッピングするには、Lambda 関数は、「プロキシ統合のための Lambda 関数の出力形式」で設営されている形式で結果を出力する必要があります。

ANY メソッドによるプロキシリソースの Lambda プロキシ統合では、単一のバックエンド Lambda 関数が、プロキシリソースを通じてすべてのリクエストのイベントハンドラーの役割を果たします。たとえば、トラフィックパターンを記録するために、プロキシリソースの URL パスで /state/city/street/house を使用してリクエストを送信することによって、モバイルデバイスから州、市、番地、建物などの場所情報を送信できます。バックエンドの Lambda 関数は、URL パスを解析し、場所情報のタプルを DynamoDB テーブルに挿入できます。

プロキシ統合のための Lambda 関数の入力形式

Lambda プロキシ統合の場合、API Gateway は、次のようにクライアントリクエスト全体をバックエンド Lambda 関数の入力 event パラメータにマッピングします。

Copy
{ "resource": "Resource path", "path": "Path parameter", "httpMethod": "Incoming request's method name" "headers": {Incoming request headers} "queryStringParameters": {query string parameters } "pathParameters": {path parameters} "stageVariables": {Applicable stage variables} "requestContext": {Request context, including authorizer-returned key-value pairs} "body": "A JSON string of the request payload." "isBase64Encoded": "A boolean flag to indicate if the applicable request payload is Base64-encode" }

具体例として、次の POST リクエストを使用し、ステージ変数を stageVariableName=stageVariableValue として testStage にデプロイした API を示します。

Copy
POST /testStage/hello/world?name=me HTTP/1.1 Host: gy415nuibc.execute-api.us-east-1.amazonaws.com Content-Type: application/json headerName: headerValue { "a": 1 }

上のリクエストにより、バックエンドの Lambda 関数から返された出力を含む次のレスポンスペイロードが生成されます。input は Lambda 関数への event パラメータに設定されています。

Copy
{ "message": "Hello me!", "input": { "resource": "/{proxy+}", "path": "/hello/world", "httpMethod": "POST", "headers": { "Accept": "*/*", "Accept-Encoding": "gzip, deflate", "cache-control": "no-cache", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Desktop-Viewer": "true", "CloudFront-Is-Mobile-Viewer": "false", "CloudFront-Is-SmartTV-Viewer": "false", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Viewer-Country": "US", "Content-Type": "application/json", "headerName": "headerValue", "Host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "Postman-Token": "9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f", "User-Agent": "PostmanRuntime/2.4.5", "Via": "1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)", "X-Amz-Cf-Id": "pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A==", "X-Forwarded-For": "54.240.196.186, 54.182.214.83", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https" }, "queryStringParameters": { "name": "me" }, "pathParameters": { "proxy": "hello/world" }, "stageVariables": { "stageVariableName": "stageVariableValue" }, "requestContext": { "accountId": "12345678912", "resourceId": "roq9wj", "stage": "testStage", "requestId": "deef4878-7910-11e6-8f14-25afc3e9ae33", "identity": { "cognitoIdentityPoolId": null, "accountId": null, "cognitoIdentityId": null, "caller": null, "apiKey": null, "sourceIp": "192.168.196.186", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": null, "userAgent": "PostmanRuntime/2.4.5", "user": null }, "resourcePath": "/{proxy+}", "httpMethod": "POST", "apiId": "gy415nuibc" }, "body": "{\r\n\t\"a\": 1\r\n}", "isBase64Encoded": false } }

Lambda への入力では、requestContext オブジェクトはキーと値のペアのマップです。キーは $context 変数のプロパティ名であり、値は対応する $context 変数のプロパティ値です。API Gateway はマップに新しいキーを追加する場合があります。有効になっている機能に応じて、requestContext マップは API ごとに異なる場合があります。たとえば、前述の例では、API に対して有効になっているカスタムオーソライザーがないため、$context.authorizer.* プロパティはありません。

注記

API Gateway は、Lambda プロキシ統合または HTTP プロキシ統合を使用した処理方法に一定の制約と制限を設定しています。詳細については、「既知の問題」を参照してください。

プロキシ統合のための Lambda 関数の出力形式

Lambda プロキシ統合では、以下の JSON 形式に従って出力を返すために、API Gateway はバックエンドの Lambda 関数を必要とします。

Copy
{ "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "body": "..." }

この例では、他に追加のレスポンスヘッダーが返されない場合は headers を指定しないことができ、body はメソッドレスポンスペイロードとしてフロントエンドにマーシャリングされます。body がバイナリ BLOB の場合は、これを Base 64 でエンコードされた文字列としてエンコードし、isBase64Encodedtrue に設定できます。それ以外の場合は、false に設定するか、指定しないでおくことができます。

関数出力が別の形式である場合、API Gateway は 502 Bad Gateway エラーレスポンスを返します。

Node.js の Lambda 関数の場合、正常なレスポンスを返すには、callback(null, {"statusCode": 200, "body": "results"}) を呼び出します。例外をスローするには、callback(new Error('internal server error')) を呼び出します。クライアント側エラーの場合 (必要なパラメータがない場合など)、callback(null, {"statusCode": 400, "body": "Missing parameters of ..."}) を呼び出して、例外をスローせずにエラーを返すことができます。