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 간의 차이점을 보여줍니다.

• 형식 2.0에는 multiValueHeaders 또는 multiValueQueryStringParameters 필드가 없습니다. 중복 헤더는 쉼표로 결합되어 headers 필드에 포함됩니다. 중복 쿼리 문자열은 쉼표로 결합되어 queryStringParameters 필드에 포함됩니다.

• 2.0 형식은 rawPath를 갖습니다. API 매핑을 사용하여 스테이지를 사용자 지정 도메인 이름에 연결하는 경우 rawPath에서 API 매핑 값을 제공하지 않습니다. 1.0 및 path 형식을 사용하여 사용자 지정 도메인 이름의 API 매핑에 액세스할 수 있습니다.

• 형식 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 함수가 반환해야 하는 응답 구조를 결정합니다.

형식 1.0에 대한 Lambda 함수 응답

1.0 형식 버전에서는 Lambda 통합이 다음 JSON 형식으로 응답을 반환해야 합니다.

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

형식 2.0에 대한 Lambda 함수 응답

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!"
}