Amazon API Gateway 엔드포인트로 Lambda 함수 호출

Amazon API Gateway 엔드포인트로 Lambda 함수 호출

Amazon API Gateway를 사용해 Lambda 함수용 HTTP 엔드포인트가 있는 웹 API를 만들 수 있어요. API Gateway는 HTTP 요청을 Lambda 함수로 라우팅하는 웹 API를 만들고 문서화하는 도구를 제공해요. 인증·권한 부여 컨트롤로 API 접근을 보호할 수 있죠. API는 인터넷을 통해 트래픽을 서빙하거나 VPC 내에서만 접근 가능하게 할 수 있어요.

팁
Lambda는 HTTP 엔드포인트로 함수를 호출하는 두 가지 방법을 제공해요: API Gateway와 Lambda 함수 URL. 어떤 방법이 여러분의 사용 사례에 가장 좋은지 잘 모르겠다면 HTTP 요청으로 Lambda 함수를 호출할 방법 선택을 참고하세요.

API의 리소스는 GET이나 POST 같은 하나 이상의 메서드를 정의해요. 메서드에는 요청을 Lambda 함수나 다른 통합 유형으로 라우팅하는 통합(integration)이 있죠. 각 리소스와 메서드를 개별적으로 정의하거나, 특수 리소스·메서드 유형을 사용해 패턴에 맞는 모든 요청을 매칭할 수 있어요. 프록시 리소스(proxy resource)는 리소스 아래의 모든 경로를 잡아내요. ANY 메서드는 모든 HTTP 메서드를 잡아냅니다.

출처: AWS Lambda 개발자 안내서

본문

Topics(주제)

• API 유형 선택
• Lambda 함수에 엔드포인트 추가
• 프록시 통합
• 이벤트 형식
• 응답 형식
• 권한
• 샘플 애플리케이션
• Powertools for AWS Lambda의 이벤트 핸들러
• 튜토리얼: Lambda를 API Gateway와 함께 사용
• API Gateway API로 Lambda 오류 처리
• HTTP 요청으로 Lambda 함수를 호출할 방법 선택

API 유형 선택

API Gateway는 Lambda 함수를 호출하는 세 가지 유형의 API를 지원해요:

• HTTP API: 가볍고 지연 시간이 낮은 RESTful API예요.
• REST API: 커스터마이즈 가능하고 기능이 풍부한 RESTful API예요.
• WebSocket API: 전이중(full-duplex) 통신을 위해 클라이언트와 영구 연결을 유지하는 웹 API예요.

HTTP API와 REST API는 모두 HTTP 요청을 처리하고 응답을 반환하는 RESTful API예요. HTTP API는 더 최신이며 API Gateway version 2 API로 빌드돼요. HTTP API의 새로운 기능은 다음과 같아요:

HTTP API 기능

• 자동 배포 – 라우트나 통합을 수정하면 자동 배포가 활성화된 스테이지에 변경 사항이 자동 배포돼요.
• 기본 스테이지 – API URL의 루트 경로에서 요청을 서빙하는 기본 스테이지($default)를 만들 수 있어요. 명명된 스테이지에서는 경로 시작 부분에 스테이지 이름을 포함해야 해요.
• CORS 구성 – 함수 코드에서 수동으로 추가하는 대신, API가 나가는 응답에 CORS 헤더를 추가하도록 구성할 수 있어요.

REST API는 API Gateway가 출시 이후 지원해 온 클래식 RESTful API예요. REST API는 현재 더 많은 커스터마이즈, 통합, 관리 기능을 갖고 있어요.

REST API 기능

• 통합 유형 – REST API는 커스텀 Lambda 통합을 지원해요. 커스텀 통합으로 요청 본문만 함수에 보내거나, 함수로 보내기 전에 요청 본문에 변환 템플릿을 적용할 수 있어요.
• 접근 제어 – REST API는 더 많은 인증·권한 부여 옵션을 지원해요.
• 모니터링 및 추적 – REST API는 AWS X-Ray 추적과 추가 로깅 옵션을 지원해요.

자세한 비교는 API Gateway 개발자 안내서의 HTTP API와 REST API 중 선택을 참고하세요.

WebSocket API도 API Gateway version 2 API를 사용하며 비슷한 기능 세트를 지원해요. 클라이언트와 API 사이의 영구 연결이 유익한 애플리케이션에는 WebSocket API를 사용하세요. WebSocket API는 전이중 통신을 제공하므로, 클라이언트와 API 양쪽 모두 응답을 기다리지 않고 메시지를 계속 보낼 수 있어요.

HTTP API는 단순화된 이벤트 형식(버전 2.0)을 지원해요. HTTP API의 이벤트 예제는 API Gateway에서 HTTP API용 AWS Lambda 프록시 통합 생성을 참고하세요.

자세한 내용은 API Gateway에서 HTTP API용 AWS Lambda 프록시 통합 생성을 참고하세요.

Lambda 함수에 엔드포인트 추가

Lambda 함수에 공개 엔드포인트 추가하기

1. Lambda 콘솔의 함수 페이지를 엽니다.
2. 함수를 선택합니다.
3. Function overview(함수 개요) 아래에서 Add trigger(트리거 추가)를 선택합니다.
4. API Gateway를 선택합니다.
5. Create an API(API 생성) 또는 Use an existing API(기존 API 사용)를 선택합니다.
   1. New API: API type(API 유형)에서 HTTP API를 선택합니다. 자세한 내용은 API 유형 선택을 참고하세요.
   2. Existing API: 드롭다운 목록에서 API를 선택하거나 API ID(예: r3pmxmplak)를 입력합니다.
6. Security(보안)에서 Open을 선택합니다.
7. Add(추가)를 선택합니다.

프록시 통합

API Gateway API는 스테이지, 리소스, 메서드, 통합으로 구성돼요. 스테이지와 리소스가 엔드포인트의 경로를 결정해요:

API 경로 형식

• /prod/ – prod 스테이지와 루트 리소스.
• /prod/user – prod 스테이지와 user 리소스.
• /dev/{proxy+} – dev 스테이지의 모든 라우트.
• / – (HTTP API) 기본 스테이지와 루트 리소스.

Lambda 통합은 경로와 HTTP 메서드 조합을 Lambda 함수에 매핑해요. API Gateway가 HTTP 요청 본문을 그대로 전달하도록(커스텀 통합) 구성하거나, 헤더·리소스·경로·메서드를 포함한 모든 요청 정보를 담은 문서로 요청 본문을 캡슐화하도록(프록시 통합) 구성할 수 있어요.

자세한 내용은 API Gateway의 Lambda 프록시 통합을 참고하세요.

이벤트 형식

Amazon API Gateway는 HTTP 요청의 JSON 표현을 담은 이벤트로 함수를 동기식으로 호출해요. 커스텀 통합의 경우 이벤트는 요청 본문이에요. 프록시 통합의 경우 이벤트는 정의된 구조를 가져요. API Gateway REST API의 프록시 이벤트 예제는 API Gateway 개발자 안내서의 프록시 통합용 Lambda 함수 입력 형식을 참고하세요.

응답 형식

API Gateway는 함수의 응답을 기다렸다가 결과를 호출자에게 중계해요. 커스텀 통합의 경우 함수 출력을 HTTP 응답으로 변환하는 통합 응답과 메서드 응답을 정의해요. 프록시 통합의 경우 함수는 특정 형식의 응답 표현으로 응답해야 해요.

다음 예제는 Node.js 함수의 응답 객체를 보여줘요. 응답 객체는 JSON 문서를 담은 성공적인 HTTP 응답을 나타내요.

예제 index.mjs – 프록시 통합 응답 객체 (Node.js)

var response = {
      "statusCode": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "isBase64Encoded": false,
      "multiValueHeaders": { 
        "X-Custom-Header": ["My value", "My other value"],
      },
      "body": "{\n  \"TotalCodeSize\": 104330022,\n  \"FunctionCount\": 26\n}"
    }

Lambda 런타임은 응답 객체를 JSON으로 직렬화해 API로 보내요. API는 응답을 파싱해 HTTP 응답을 만든 뒤, 원래 요청을 한 클라이언트에게 보냅니다.

예제 HTTP 응답

< HTTP/1.1 200 OK
  < Content-Type: application/json
  < Content-Length: 55
  < Connection: keep-alive
  < x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356
  < X-Custom-Header: My value
  < X-Custom-Header: My other value
  < X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036
  <
  {
    "TotalCodeSize": 104330022,
    "FunctionCount": 26
  }

권한

Amazon API Gateway는 함수의 리소스 기반 정책에서 함수 호출 권한을 얻어요. 전체 API에 호출 권한을 부여하거나, 스테이지·리소스·메서드에 제한된 접근을 부여할 수 있어요.

Lambda 콘솔, API Gateway 콘솔 또는 AWS SAM 템플릿으로 함수에 API를 추가하면 함수의 리소스 기반 정책이 자동으로 업데이트돼요. 다음은 예제 함수 정책이에요.

예제 함수 정책

---

{
  "Version":"2012-10-17",		 		 	
  "Id": "default",
  "Statement": [
    {
      "Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F",
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:us-east-2:{{111122223333}}:function:nodejs-apig-function-1G3MXMPLXVXYI",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:execute-api:us-east-2:{{111122223333}}:ktyvxmpls1/*/GET/"
        }
      }
    }
  ]
}

다음 API 작업으로 함수 정책 권한을 수동으로 관리할 수 있어요:

• AddPermission
• RemovePermission
• GetPolicy

기존 API에 호출 권한을 부여하려면 add-permission 명령을 사용하세요. 예:

aws lambda add-permission \
  --function-name my-function \
  --statement-id apigateway-get --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"

다음과 같은 출력이 보일 거예요:

{
    "Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}"
}

참고
함수와 API가 서로 다른 AWS 리전에 있으면 소스 ARN의 리전 식별자가 API의 리전이 아니라 함수의 리전과 일치해야 해요. API Gateway가 함수를 호출할 때 API의 ARN을 기반으로 하되 함수의 리전에 맞게 수정된 리소스 ARN을 사용하기 때문이에요.

이 예제의 소스 ARN은 ID가 mnh1xmpli7인 API의 default 스테이지에 있는 루트 리소스의 GET 메서드에 있는 통합에 권한을 부여해요. 소스 ARN에 별표(asterisk)를 사용해 여러 스테이지, 메서드, 리소스에 권한을 부여할 수 있어요.

리소스 패턴

• mnh1xmpli7/*/GET/* – 모든 스테이지의 모든 리소스에서 GET 메서드.
• mnh1xmpli7/prod/ANY/user – prod 스테이지의 user 리소스에서 ANY 메서드.
• mnh1xmpli7/*/*/* – 모든 스테이지의 모든 리소스에서 모든 메서드.

정책을 보고 문을 제거하는 방법에 대한 자세한 내용은 Lambda에서 리소스 기반 정책 작업을 참고하세요.

샘플 애플리케이션

API Gateway with Node.js 샘플 앱에는 AWS X-Ray 추적이 활성화된 REST API를 만드는 AWS SAM 템플릿이 있는 함수가 포함돼 있어요. 함수 배포, 호출, API 테스트, 정리용 스크립트도 포함되죠.

Powertools for AWS Lambda의 이벤트 핸들러

Powertools for AWS Lambda 도구 키트의 이벤트 핸들러는 API Gateway 엔드포인트(HTTP 또는 REST)가 호출하는 Lambda 함수를 작성할 때 라우팅, 미들웨어, CORS 구성, OpenAPI 사양 생성, 요청 검증, 오류 처리 등 유용한 기능을 제공해요. 이벤트 핸들러 유틸리티는 Python과 TypeScript/JavaScript에서 사용할 수 있어요. 자세한 내용은 Powertools for AWS Lambda (Python) 문서의 Event Handler REST API와 Powertools for AWS Lambda (TypeScript) 문서의 Event Handler HTTP API를 참고하세요.

Python

from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext

app = APIGatewayRestResolver()
logger = Logger()

@app.get("/healthz")
def ping():
    return {"message": "health status ok"}

@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)  
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

TypeScript

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import {
  correlationPaths,
  search,
} from '@aws-lambda-powertools/logger/correlationId';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({
  correlationIdSearchFn: search,
});

const app = new Router({ logger });

app.get("/healthz", async () => {
  return { message: "health status ok" };
});

export const handler = async (event: unknown, context: Context) => {
  // You can continue using other utilities just as before
  logger.addContext(context);
  logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST);
  return app.resolve(event, context);
};

더 알아보기 (Learn more)

• HTTP/REST/WebSocket API 유형 선택, 엔드포인트 추가, 프록시 통합, 이벤트·응답 형식, 권한, Powertools 이벤트 핸들러까지 살펴보세요.