Amazon API Gateway
개발자 안내서

API Gateway에서 Lambda 프록시 통합 설정

API Gateway Lambda 프록시 통합 이해

Amazon API Gateway Lambda 프록시 통합은 단일 API 메서드의 설정을 통해 API를 구축하기 위한 간단하고 강력하며 민첩한 메커니즘입니다. Lambda 프록시 통합을 사용하면 클라이언트가 백엔드에서 단일 Lambda 함수를 호출할 수 있습니다. 이 함수는 다른 Lambda 함수를 호출하는 등 다른 AWS 서비스의 많은 리소스 또는 기능에 액세스합니다.

Lambda 프록시 통합에서 클라이언트가 API 요청을 제출하면 API Gateway는 통합된 Lambda 함수로 원래 요청을 있는 그대로 전달합니다. 단, 요청 파라미터의 순서는 유지되지 않습니다. 요청 데이터에는 요청 헤더, 쿼리 문자열 파라미터, URL 경로 변수, 페이로드 및 API 구성 데이터가 포함되어 있습니다. 구성 데이터에는 현재 배포 단계 이름, 단계 변수, 사용자 ID 또는 권한 부여 컨텍스트(있는 경우)가 포함될 수 있습니다. 백엔드 Lambda 함수는 수신되는 요청 데이터를 구문 분석하여 반환하는 응답을 결정합니다. API Gateway에서 Lambda 출력을 클라이언트에 대한 API 응답으로 전달하려면 Lambda 함수에서 이 형식으로 결과를 반환해야 합니다.

API Gateway는 Lambda 프록시 통합을 위해 클라이언트와 백엔드 Lambda 함수 사이에 개입하지 않기 때문에 클라이언트와 통합된 Lambda 함수는 API의 기존 통합 설정을 깨지 않고 서로의 변화에 맞게 조정할 수 있습니다. 이렇게 하려면 클라이언트가 백엔드 Lambda 함수에 의해 제정된 애플리케이션 프로토콜을 따라야 합니다.

모든 API 메서드에 대해 Lambda 프록시 통합을 설정할 수 있습니다. 그러나 Lambda 프록시 통합은 일반 프록시 리소스가 포함된 API 메소드에 대해 구성될 때 더 강력합니다. 일반 프록시 리소스는 {proxy+}의 특수 템플릿 경로 변수, catch-all ANY 메서드 자리 표시자 또는 둘 다로 표시될 수 있습니다. 클라이언트는 수신되는 요청의 백엔드 Lambda 함수에 대한 입력을 요청 파라미터 또는 해당 페이로드로 전달할 수 있습니다. 요청 파라미터에는 헤더, URL 경로 변수, 쿼리 문자열 파라미터 및 해당 페이로드가 포함되어 있습니다. 통합된 Lambda 함수는 필요한 입력이 누락된 경우 요청을 처리하고 의미 있는 오류 메시지로 클라이언트에 응답하기 전에 모든 입력 소스를 확인합니다.

일반 HTTP 메서드 ANY 및 일반 리소스 {proxy+}와 통합된 API 메서드를 호출할 때 클라이언트는 ANY 대신 특정 HTTP 메서드를 사용하여 요청을 제출합니다. 또한 클라이언트는 {proxy+} 대신 특정 URL 경로를 지정하고 필수 헤더, 쿼리 문자열 파라미터 또는 해당 페이로드를 포함합니다.

다음 목록에는 Lambda 프록시 통합을 통해 다양한 API 메서드의 런타임 동작이 요약되어 있습니다.

  • ANY /{proxy+}: 클라이언트는 특정 HTTP 메서드를 선택하고 특정 리소스 경로 계층을 설정해야 하며 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.

  • ANY /res: 클라이언트는 특정 HTTP 메서드를 선택해야 하고 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.

  • GET|POST|PUT|... /{proxy+}: 클라이언트는 특정 리소스 경로 계층, 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.

  • GET|POST|PUT|... /res/{path}/...: 클라이언트는 특정 경로 세그먼트({path} 변수의 경우)를 선택해야 하고 요청 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 입력 데이터를 통합된 Lambda 함수에 전달할 수 있습니다.

  • GET|POST|PUT|... /res: 클라이언트는 요청 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 선택하여 입력 데이터를 통합된 Lambda 함수에 전달할 수 있습니다.

프록시 리소스 {proxy+} 및 사용자 지정 리소스 {custom} 모두 템플릿 경로 변수로 표현됩니다. 그러나 {proxy+}는 경로 계층을 따라 모든 리소스를 참조할 수 있지만 {custom}은 특정 경로 세그먼트만 참조합니다. 예를 들어 식품 매장은 부서 이름, 생산 카테고리 및 제품 유형별로 온라인 제품 재고를 구성할 수 있습니다. 식품 매장의 웹 사이트는 사용자 지정 리소스의 템플릿 경로 변수인 /{department}/{produce-category}/{product-type}을 사용하여 사용 가능한 제품을 나타낼 수 있습니다. 예를 들어 사과는 /produce/fruit/apple로, 당근은 /produce/vegetables/carrot으로 표현됩니다. 또한 /{proxy+}를 사용하여 온라인 매장에서 쇼핑하는 동안 고객이 검색할 수 있는 부서, 생산 카테고리 또는 제품 유형을 나타낼 수 있습니다. 예를 들어 /{proxy+}는 다음 항목 중 하나를 참조할 수 있습니다.

  • /produce

  • /produce/fruit

  • /produce/vegetables/carrot

고객이 사용 가능한 제품, 제품 카테고리 및 관련 매장 부서를 검색할 수 있게 하려면 읽기 전용 권한으로 GET /{proxy+}의 단일 메서드를 공개할 수 있습니다. 마찬가지로 감독자가 produce 부서의 재고를 업데이트할 수 있게 하려면 읽기/쓰기 권한으로 PUT /produce/{proxy+}의 또 다른 단일 메서드를 설정할 수 있습니다. 점원이 야채의 총 누계를 업데이트할 수 있게 하려면 읽기/쓰기 권한으로 POST /produce/vegetables/{proxy+} 메서드를 설정할 수 있습니다. 매장 관리자가 사용 가능한 제품에 대해 가능한 조치를 수행할 수 있게 하려면 온라인 매장 개발자는 읽기/쓰기 권한으로 ANY /{proxy+} 메서드를 공개할 수 있습니다. 어떤 경우에도 런타임 시 고객 또는 직원은 선택한 부서에서 지정된 유형의 특정 제품, 선택한 부서의 특정 생산 카테고리 또는 특정 부서를 선택해야 합니다.

API Gateway 프록시 통합 설정에 대한 자세한 내용은 프록시 리소스를 사용하여 프록시 통합을 설정를 참조하십시오.

프록시 통합을 위해서는 클라이언트가 백엔드 요구 사항에 대해 보다 자세한 지식을 갖추고 있어야 합니다. 따라서 최적의 앱 성능과 사용자 경험을 보장하려면 백엔드 개발자는 클라이언트 개발자에게 백엔드 요구 사항을 명확하게 전달하고 요구 사항이 충족되지 않으면 강력한 오류 피드백 메커니즘을 제공해야 합니다.

다중 값 헤더 및 쿼리 문자열 파라미터에 대한 지원

API Gateway는 동일한 이름을 지닌 복수의 헤더 및 쿼리 문자열 파라미터를 지원합니다. 다중 값 헤더와 단일 값 헤더 및 파라미터는 동일한 요청 및 응답에서 결합될 수 있습니다. 자세한 내용은 프록시 통합에 대한 Lambda 함수의 입력 형식프록시 통합에 대한 Lambda 함수의 출력 형식 단원을 참조하십시오.

Lambda 프록시 리소스를 사용하여 프록시 리소스 설정

Lambda 프록시 통합 유형을 사용하여 프록시 리소스를 설정하려면 복잡한 경로 파라미터(예: /parent/{proxy+})를 사용하여 API 리소스를 생성한 후 이 리소스를 ANY 메서드의 Lambda 함수 백엔드(예: arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource)와 통합합니다. 복잡한 경로 파라미터는 API 리소스 경로의 끝에 와야 합니다. 비 프록시 리소스를 사용할 때와 마찬가지로 API Gateway 콘솔을 사용하거나 OpenAPI 정의 파일을 가져오거나 API Gateway REST API를 직접 호출하여 프록시 리소스를 설정할 수 있습니다.

다음 OpenAPI API 정의 파일은 SimpleLambda4ProxyResource이라는 Lambda 함수에 통합된 프록시 리소스를 포함하는 API의 예를 보여줍니다.

OpenAPI 3.0OpenAPI 2.0
OpenAPI 3.0
{ "openapi": "3.0.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "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" } } } }, "servers": [ { "url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/testStage" } } } ] }
OpenAPI 2.0
{ "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 테이블에 삽입할 수 있습니다.

AWS CLI를 사용하여 Lambda 프록시 통합을 설정

이 단원에서는 AWS CLI를 사용하여 Lambda 프록시 통합으로 API를 설정하는 방법을 보여줍니다.

참고

API Gateway 콘솔을 사용하여 Lambda 프록시 통합을 통해 프록시 리소스를 구성하는 방법에 대한 자세한 내용은 자습서: Lambda 프록시 통합을 사용하여 Hello World API 빌드 단원을 참조하십시오.

예를 들면 다음과 같은 샘플 Lambda 함수를 API의 백엔드로 사용합니다.

exports.handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); var res ={ "statusCode": 200, "headers": { "Content-Type": "*/*" } }; var greeter = 'World'; if (event.greeter && event.greeter!=="") { greeter = event.greeter; } else if (event.body && event.body !== "") { var body = JSON.parse(event.body); if (body.greeter && body.greeter !== "") { greeter = body.greeter; } } else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") { greeter = event.queryStringParameters.greeter; } else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") { greeter = event.multiValueHeaders.greeter.join(" and "); } else if (event.headers && event.headers.greeter && event.headers.greeter != "") { greeter = event.headers.greeter; } res.body = "Hello, " + greeter + "!"; callback(null, res); };

이를 Lambda 사용자 지정 통합 설정과 비교하여 이 Lambda 함수에 대한 입력을 요청 파라미터 및 본문으로 표현할 수 있습니다. 클라이언트가 동일한 입력 데이터를 전달하도록 허용하는 더 많은 위도가 있습니다. 여기에서 클라이언트는 greeter의 이름을 쿼리 문자열 파라미터, 헤더 또는 본문 속성으로 전달할 수 있습니다. 함수는 Lambda 사용자 지정 통합도 지원합니다. API 설정은 더 간단합니다. 메서드 응답 또는 통합 응답은 전혀 구성하지 않습니다.

AWS CLI를 사용하여 Lambda 프록시 통합을 설정하려면

  1. 다음과 같이 create-rest-api 명령을 호출하여 API를 생성합니다.

    aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' --region us-west-2

    다음과 같이 그 결과로 얻은 응답에 있는 API의 id 값(te6si5ach7)을 적어 둡니다.

    { "name": "HelloWorldProxy (AWS CLI)", "id": "te6si5ach7", "createdDate": 1508461860 }

    이 단원 전체에서 API id가 필요합니다.

  2. 다음과 같이 get-resources 명령을 호출하여 루트 리소스 id를 가져옵니다.

    aws apigateway get-resources --rest-api-id te6si5ach7 --region us-west-2

    이 작업이 성공하면 그 응답은 다음과 같습니다.

    { "items": [ { "path": "/", "id": "krznpq9xpg" } ] }

    루트 리소스 id 값(krznpq9xpg)을 기록해 둡니다. 다음 단계 및 그 이후에 이 값이 필요합니다.

  3. 다음과 같이 create-resource를 호출하여 /greeting의 API Gateway 리소스를 생성합니다.

    aws apigateway create-resource --rest-api-id te6si5ach7 \ --region us-west-2 \ --parent-id krznpq9xpg \ --path-part {proxy+}

    성공적인 응답은 다음과 같습니다.

    { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "2jf6xt", "parentId": "krznpq9xpg" }

    {proxy+} 리소스의 id 값(2jf6xt)을 기록해 둡니다. 다음 단계에서 /{proxy+} 리소스에 메서드를 생성하려면 이 값이 필요합니다.

  4. 다음과 같이 put-method를 호출하여 ANYANY /{proxy+} 메서드 요청을 생성합니다.

    aws apigateway put-method --rest-api-id te6si5ach7 \ --region us-west-2 \ --resource-id 2jf6xt \ --http-method ANY \ --authorization-type "NONE"

    성공적인 응답은 다음과 같습니다.

    { "apiKeyRequired": false, "httpMethod": "ANY", "authorizationType": "NONE" }

    이 API 메서드를 통해 클라이언트는 백엔드에서 Lambda 함수의 인사를 수신 또는 발신할 수 있습니다.

  5. put-integration을 호출하여 HelloWorld라는 Lambda 함수로 ANY /{proxy+} 메서드의 통합을 설정합니다. 이 함수는 "Hello, {name}!" 파라미터가 제공되면 greeter이라는 메시지로, 쿼리 문자열 파라미터가 설정되어 있지 않으면 "Hello, World!"라는 메시지로 요청에 응답합니다.

    aws apigateway put-integration \ --region us-west-2 --rest-api-id vaz7da96z6 \ --resource-id 2jf6xt \ --http-method ANY \ --type AWS_PROXY \ --integration-http-method POST \ --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole

    중요

    Lambda 통합의 경우에는 함수 호출을 위한 Lambda 서비스 작업의 사양에 따라 통합 요청에 대해 POST의 HTTP 메서드를 사용해야 합니다. apigAwsProxyRole의 IAM 역할에는 apigateway 서비스가 Lambda 함수를 호출하도록 허용하는 정책이 있어야 합니다. IAM 권한에 대한 자세한 내용은 API 호출을 위한 API Gateway 권한 모델 단원을 참조하십시오.

    성공적인 출력 결과는 다음과 같습니다.

    { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:1234567890:function:HelloWorld/invocations", "httpMethod": "POST", "cacheNamespace": "vvom7n", "credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole", "type": "AWS_PROXY" }

    credentials에 IAM 역할을 제공하는 대신 add-permission 명령을 호출하여 리소스 기반 권한을 추가할 수 있습니다. 이 작업은 API Gateway 콘솔이 수행합니다.

  6. 다음과 같이 create-deployment를 호출하여 API를 test 단계에 배포합니다.

    aws apigateway create-deployment --rest-api-id te6si5ach7 --stage-name test
  7. 터미널에서 다음 cURL 명령을 사용하여 API를 테스트합니다.

    ?greeter=jane이라는 쿼리 문자열 파라미터와 함께 API를 호출:

    curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane' \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, \ SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'

    greeter:jane이라는 헤더 파라미터와 함께 API를 호출:

    curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, \ SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' \ -H 'content-type: application/json' \ -H 'greeter: jane'

    {"greeter":"jane"}이라는 본문과 함께 API를 호출:

    curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, \ SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' -H 'content-type: application/json' \ -d '{ "greeter": "jane" }'

    이 모든 경우에 출력되는 것은 다음과 같은 응답 본문이 있는 200 응답입니다.

    Hello, jane!

프록시 통합에 대한 Lambda 함수의 입력 형식

Lambda 프록시 통합을 사용할 경우 API Gateway에서 전체 클라이언트 요청을 백엔드 Lambda 함수의 입력 event 파라미터에 다음과 같이 매핑합니다.

{ "resource": "Resource path", "path": "Path parameter", "httpMethod": "Incoming request's method name" "headers": {String containing incoming request headers} "multiValueHeaders": {List of strings containing incoming request headers} "queryStringParameters": {query string parameters } "multiValueQueryStringParameters": {List of 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" }

참고

입력에서:

  • headers 키에는 단일 값 헤더만 있습니다.

  • multiValueHeaders 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다.

  • headersmultiValueHeaders 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, multiValueHeaders의 값만이 병합된 목록에 표시됩니다.

다음 POST 요청에서는 stageVariableName=stageVariableValue라는 단계 변수로 testStage에 배포되는 API를 보여줍니다.

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 파라미터로 설정되어 있습니다.

{ "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" }, "multiValueHeaders":{ '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", "multivalueName": "me" }, "multiValueQueryStringParameters":{ "name":[ "me" ], "multivalueName":[ "you", "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 변수 속성의 이름이고, 값은 그 속성의 값입니다. API Gateway는 맵에 새 키를 추가할 수 있습니다.

활성화된 기능에 따라 requestContext 맵은 API마다 다를 수 있습니다. 예를 들어 앞의 예제에서는 권한 부여 유형이 지정되지 않았으므로 $context.authorizer.* 또는 $context.identity.* 속성이 없습니다. 권한 부여 유형이 지정된 경우에는 다음과 같이 API Gateway가 requestContext.identity 객체의 통합 엔드포인트에 권한 부여된 사용자 정보를 전달합니다.

  • 권한 부여 유형이 AWS_IAM인 경우, 권한 부여된 사용자 정보에 $context.identity.* 속성이 포함됩니다.

  • 권한 부여 유형이 COGNITO_USER_POOLS(Amazon Cognito 권한 부여자)인 경우, 권한 부여된 사용자 정보에 $context.identity.cognito*$context.authorizer.claims.* 속성이 포함됩니다.

  • 권한 부여 유형이 CUSTOM(Lambda 권한 부여자)인 경우, 권한 부여된 사용자 정보에 $context.authorizer.principalId 및 기타 적용되는 $context.authorizer.* 속성이 포함됩니다.

다음은 권한 부여 유형이 AWS_IAM으로 설정되었을 때 Lambda 프록시 통합 엔드포인트로 전달되는 requestContext의 예입니다.

{ ..., "requestContext": { "requestTime": "20/Feb/2018:22:48:57 +0000", "path": "/test/", "accountId": "123456789012", "protocol": "HTTP/1.1", "resourceId": "yx5mhem7ye", "stage": "test", "requestTimeEpoch": 1519166937665, "requestId": "3c3ecbaa-1690-11e8-ae31-8f39f1d24afd", "identity": { "cognitoIdentityPoolId": null, "accountId": "123456789012", "cognitoIdentityId": null, "caller": "AIDAJ........4HCKVJZG", "sourceIp": "51.240.196.104", "accessKey": "IAM_user_access_key", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": "arn:aws:iam::123456789012:user/alice", "userAgent": "PostmanRuntime/7.1.1", "user": "AIDAJ........4HCKVJZG" }, "resourcePath": "/", "httpMethod": "GET", "apiId": "qr2gd9cfmf" }, ... }

프록시 통합에 대한 Lambda 함수의 출력 형식

Lambda 프록시 통합을 사용할 경우 API Gateway에서는 백엔드 Lambda 함수에 다음 JSON 형식에 따라 출력을 반환하도록 요구합니다.

{ "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "body": "..." }

출력에서:

  • 출력에서 추가 응답 헤더가 반환되지 않을 경우 headersmultiValueHeaders 키가 비지정 상태일 수 있습니다.

  • headers 키에는 단일 값 헤더만 있습니다.

  • multiValueHeaders 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다. multiValueHeaders 키를 사용하여 모든 단일 값 헤더를 포함하는 모든 추가 헤더를 지정할 수 있습니다.

  • headersmultiValueHeaders 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, multiValueHeaders의 값만이 병합된 목록에 표시됩니다.

Lambda 프록시 통합에 대해 CORS를 활성화하려면 출력 headersAccess-Control-Allow-Origin:domain-name을 추가해야 합니다. domain-name은 모든 도메인 이름에 대해 *일 수 있습니다. 출력 body는 프런트엔드에 메서드 응답 페이로드로 마샬링됩니다. body가 이진 BLOB인 경우 isBase64Encodedtrue으로 설정하고, 이진 미디어 형식/로 구성하여 Base64로 인코딩된 문자열로 인코딩할 수 있습니다. 그렇지 않은 경우 false로 설정하거나 지정되지 않은 상태로 둘 수 있습니다.

참고

이진 지원 활성화에 대한 자세한 내용은 API Gateway 콘솔을 사용하여 이진 지원 활성화 단원을 참조하십시오.

함수 출력의 형식이 다른 경우 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 ..."})를 호출하여 예외를 발생하지 않고 오류를 반환할 수 있습니다.

Node.js 8.10의 Lambda async 함수에서 이와 동일한 구문은 다음과 같습니다.

  • 성공 결과를 반환하려면 return {"statusCode": 200, "body": "results"}을 호출합니다.

  • 예외를 발생하려면 throw new Error("internal server error")를 호출합니다.

  • 클라이언트 측 오류의 경우(예: 필요한 파라미터가 없는 경우) return {"statusCode": 400, "body": "Missing parameters of ..."}를 호출하여 예외를 발생하지 않고 오류를 반환할 수 있습니다.