API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する - Amazon API Gateway
ペイロード形式バージョンLambda 関数レスポンス形式

API Gateway で HTTP API の AWS Lambda プロキシ統合を作成する

Lambda プロキシ統合を使用すると、API ルートを Lambda 関数と統合できます。クライアントが API を呼び出すと、API Gateway はリクエストを Lambda 関数に送信し、関数のレスポンスをクライアントに返します。HTTP API の作成例については、「HTTP API を作成する」を参照してください。

ペイロード形式バージョン

ペイロード形式バージョンは、API Gateway が Lambda 統合に送信するイベントの形式と、API Gateway が Lambda からのレスポンスをどのように解釈するかを指定します。ペイロード形式バージョンを指定しない場合、AWS Management Console はデフォルトで最新バージョンを使用します。AWS CLI、AWS CloudFormation、SDK を使用して Lambda 統合を作成する場合は、payloadFormatVersion を指定する必要があります。サポートされる値は 1.0 と 2.0 です。

payloadFormatVersion を設定する方法の詳細については、「create-integration」を参照してください。既存の統合の payloadFormatVersion を確認する方法の詳細については、「get-integration」を参照してください。

ペイロード形式の相違点

次のリストは、ペイロード形式の 1.0 バージョンと 2.0 バージョンの違いを示しています。

  • Format 2.0 には multiValueHeaders または multiValueQueryStringParameters フィールドがありません。重複するヘッダーはコンマで結合され、headers フィールドに含められます。重複するクエリ文字列はコンマで結合され、queryStringParameters フィールドに含められます。

  • 形式 2.0 には rawPath があります。API マッピングを使用してステージをカスタムドメイン名に接続する場合、rawPath は API マッピング値を提供しません。カスタムドメイン名の API マッピングにアクセスするには、形式 1.0 と path を使用します。

  • 形式 2.0 には、新しい cookies フィールドが含まれています。リクエスト内のすべてのクッキーヘッダーはコンマで結合され、cookies フィールドに追加されます。クライアントへのレスポンスでは、各クッキーは set-cookie ヘッダーになります。

ペイロード形式の構造

次の例は、各ペイロード形式バージョンの構造を示しています。すべてのヘッダー名は小文字です。

2.0
{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authentication": {
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "authorizer": {
      "jwt": {
        "claims": {
          "claim1": "value1",
          "claim2": "value2"
        },
        "scopes": [
          "scope1",
          "scope2"
        ]
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "192.0.2.1",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from Lambda",
  "pathParameters": {
    "parameter1": "value1"
  },
  "isBase64Encoded": false,
  "stageVariables": {
    "stageVariable1": "value1",
    "stageVariable2": "value2"
  }
}
1.0
{
  "version": "1.0",
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "id",
    "authorizer": {
      "claims": null,
      "scopes": null
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "extendedRequestId": "request-id",
    "httpMethod": "GET",
    "identity": {
      "accessKey": null,
      "accountId": null,
      "caller": null,
      "cognitoAuthenticationProvider": null,
      "cognitoAuthenticationType": null,
      "cognitoIdentityId": null,
      "cognitoIdentityPoolId": null,
      "principalOrgId": null,
      "sourceIp": "192.0.2.1",
      "user": null,
      "userAgent": "user-agent",
      "userArn": null,
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "path": "/my/path",
    "protocol": "HTTP/1.1",
    "requestId": "id=",
    "requestTime": "04/Mar/2020:19:15:17 +0000",
    "requestTimeEpoch": 1583349317135,
    "resourceId": null,
    "resourcePath": "/my/path",
    "stage": "$default"
  },
  "pathParameters": null,
  "stageVariables": null,
  "body": "Hello from Lambda!",
  "isBase64Encoded": false
}

Lambda 関数レスポンス形式

ペイロード形式バージョンによって、Lambda 関数が返す必要があるレスポンスの構造が決まります。

Lambda 関数レスポンス形式 1.0

1.0 形式バージョンの場合、Lambda 統合は次の JSON 形式でレスポンスを返す必要があります。

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

Lambda 関数レスポンス形式 2.0

2.0 形式バージョンでは、API Gateway がレスポンス形式を推測できます。API Gateway は、Lambda 関数が有効な JSON を返し、statusCode を返さない場合、次の仮定を行います。

  • isBase64Encoded は false。

  • statusCode は 200。

  • content-type は application/json。

  • body は関数のレスポンスです。

次の例は、Lambda 関数と API Gateway の解釈の出力を示しています。

Lambda 関数出力 API Gateway 解釈 
"Hello from Lambda!"
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
 
{ "message": "Hello from Lambda!" }
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}

レスポンスをカスタマイズするには、Lambda 関数は以下の形式でレスポンスを返す必要があります。

{
    "cookies" : ["cookie1", "cookie2"],
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "body": "Hello from Lambda!"
}