"` |
| `requestContext.http` | HTTP 요청에 대한 세부 정보를 포함하는 객체입니다. | |
| `requestContext.http.method` | 이 요청에 사용되는 HTTP 메서드입니다. 유효한 값에는 `GET`, `POST`, `PUT`, `HEAD`, `OPTIONS`, `PATCH` 및 `DELETE`가 있습니다. | `GET` |
| `requestContext.http.path` | 요청 경로입니다. 예를 들어, 요청 URL이 `https://{url-id}.lambda-url.{region}.on.aws/example/test/demo`인 경우 경로 값은 `/example/test/demo`입니다. | `/example/test/demo` |
| `requestContext.http.protocol` | 요청의 프로토콜입니다. | `HTTP/1.1` |
| `requestContext.http.sourceIp` | 요청하는 즉시 TCP 연결의 소스 IP 주소입니다. | `123.123.123.123` |
| `requestContext.http.userAgent` | 사용자 에이전트 요청 헤더 값입니다. | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0` |
| `requestContext.requestId` | 호출 요청의 ID입니다. 이 ID를 사용하여 함수와 관련된 호출 로그를 추적할 수 있습니다. | `e1506fd5-9e7b-434f-bd42-4f8fa224b599` |
| `requestContext.routeKey` | 함수 URL은 이 파라미터를 사용하지 않습니다. Lambda는 이 파라미터를 자리표시자를 의미하는 `$default`로 설정합니다. | `$default` |
| `requestContext.stage` | 함수 URL은 이 파라미터를 사용하지 않습니다. Lambda는 이 파라미터를 자리표시자를 의미하는 `$default`로 설정합니다. | `$default` |
| `requestContext.time` | 요청의 타임스탬프입니다. | `"07/Sep/2021:22:50:22 +0000"` |
| `requestContext.timeEpoch` | Unix Epoch 시간으로 표시된 요청의 타임스탬프입니다. | `"1631055022677"` |
| `body` | 요청의 본문입니다. 요청의 콘텐츠 유형이 바이너리인 경우 본문은 base64로 인코딩됩니다. | `{"key1": "value1", "key2": "value2"}` |
| `pathParameters` | 함수 URL은 이 파라미터를 사용하지 않습니다. Lambda는 이 파라미터를 `null`로 설정하거나 JSON에서 제외합니다. | `null` |
| `isBase64Encoded` | 본문이 이진 페이로드이고 base64로 인코딩되는 경우 `TRUE`입니다. 그렇지 않으면 `FALSE`입니다. | `FALSE` |
| `stageVariables` | 함수 URL은 이 파라미터를 사용하지 않습니다. Lambda는 이 파라미터를 `null`로 설정하거나 JSON에서 제외합니다. | `null` |
### 응답 페이로드 형식
함수가 응답을 반환하면 Lambda는 응답을 구문 분석하여 HTTP 응답으로 변환합니다. 함수 응답 페이로드는 다음 형식을 취합니다.
```
{
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": "{ \"message\": \"Hello, world!\" }",
"cookies": [
"Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
"Cookie_2=Value2; Max-Age=78000"
],
"isBase64Encoded": false
}
```
Lambda는 응답 형식을 추론합니다. 함수가 유효한 JSON을 반환하고 `statusCode`을 반환하지 않는 경우 Lambda가 다음과 같은 가정을 합니다.
+ `statusCode`는 입니다.`200`
**참고**
유효한 `statusCode`는 100\$1599 범위 내에 있습니다.
+ `content-type`은 입니다.`application/json`
+ `body`는 함수의 응답입니다.
+ `isBase64Encoded`is(`false` )
다음 예제에서는 Lambda 함수의 출력이 응답 페이로드에 매핑되는 방법과 응답 페이로드가 최종 HTTP 응답에 매핑되는 방법을 보여 줍니다. 클라이언트가 함수 URL을 간접 호출하면 HTTP 응답이 표시됩니다.
**문자열 응답에 대한 출력 예**
| Lambda 함수 출력 | 해석된 응답 출력 | HTTP 응답(클라이언트에게 표시되는 내용) |
| --- | --- | --- |
| "Hello, world!"
| {
"statusCode": 200,
"body": "Hello, world!",
"headers": {
"content-type": "application/json"
},
"isBase64Encoded": false
} | HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 15
"Hello, world!"
|
**JSON 응답에 대한 출력 예**
| Lambda 함수 출력 | 해석된 응답 출력 | HTTP 응답(클라이언트에게 표시되는 내용) |
| --- | --- | --- |
| {
"message": "Hello, world!"
} | {
"statusCode": 200,
"body": {
"message": "Hello, world!"
},
"headers": {
"content-type": "application/json"
},
"isBase64Encoded": false
} | HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 34
{
"message": "Hello, world!"
}
|
**사용자 지정 응답에 대한 출력 예**
| Lambda 함수 출력 | 해석된 응답 출력 | HTTP 응답(클라이언트에게 표시되는 내용) |
| --- | --- | --- |
| {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"isBase64Encoded": false
} | {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"isBase64Encoded": false
} | HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
{
"message": "Hello, world!"
}
|
### Cookies
함수에서 쿠키를 반환하려면 수동으로 `set-cookie` 헤더를 추가하지 않습니다. 대신 응답 페이로드 객체에 쿠키를 포함합니다. Lambda는 이를 자동으로 해석하고 다음 예제와 같이 HTTP 응답의 `set-cookie` 헤더로서 추가합니다.
| Lambda 함수 출력 | HTTP 응답(클라이언트에게 표시되는 내용) |
| --- | --- |
| {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"cookies": [
"Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
"Cookie_2=Value2; Max-Age=78000"
],
"isBase64Encoded": false
} | HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT
set-cookie: Cookie_2=Value2; Max-Age=78000
{
"message": "Hello, world!"
}
|
# Lambda 함수 URL 모니터링
AWS CloudTrail과 Amazon CloudWatch를 사용하여 함수 URL을 모니터링할 수 있습니다.
**Topics**
+ [
## CloudTrail을 사용하여 함수 URL 모니터링
](#urls-cloudtrail)
+ [
## 함수 URL에 대한 CloudWatch 지표
](#urls-cloudwatch)
## CloudTrail을 사용하여 함수 URL 모니터링
함수 URL에 대해 Lambda는 CloudTrail 로그 파일에 다음 API 작업을 이벤트로 로깅하는 것을 자동 지원합니다.
+ [CreateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunctionUrlConfig.html)
+ [UpdateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionUrlConfig.html)
+ [DeleteFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_DeleteFunctionUrlConfig.html)
+ [GetFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionUrlConfig.html)
+ [ListFunctionUrlConfigs](https://docs.aws.amazon.com/lambda/latest/api/API_ListFunctionUrlConfigs.html)
각 로그 항목에는 호출자 자격 증명, 요청이 이루어진 시기, 기타 세부 정보에 관한 정보가 포함되어 있습니다. CloudTrail **이벤트 기록(Event history)**을 확인하면 지난 90일 이내의 모든 이벤트를 볼 수 있습니다. 90일이 지난 레코드를 보존하려면 추적을 생성할 수 있습니다.
기본적으로 CloudTrail은 데이터 이벤트로 간주하는 `InvokeFunctionUrl` 요청을 로그하지 않습니다. 그러나 CloudTrail에서 데이터 이벤트 로깅을 활성화할 수 있습니다. 자세한 내용은 *AWS CloudTrail 사용 설명서*의 [추적을 위해 데이터 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)을 참조하십시오.
## 함수 URL에 대한 CloudWatch 지표
Lambda는 함수 URL 요청에 대한 집계된 지표를 CloudWatch로 전송합니다. 이러한 지표를 사용하면 CloudWatch 콘솔에서 함수 URL을 모니터링하고 대시보드를 구축하고 경보를 구성할 수 있습니다.
함수 URL은 다음 호출 지표를 지원합니다. `Sum` 통계를 사용하여 이러한 지표를 볼 것을 권장합니다.
+ `UrlRequestCount` – 이 함수 URL에 수행된 요청 수.
+ `Url4xxCount` – 4XX HTTP 상태 코드를 반환한 요청 수. 4XX 시리즈 코드는 잘못된 요청과 같은 클라이언트 측 오류를 나타냅니다.
+ `Url5xxCount` – 5XX HTTP 상태 코드를 반환한 요청 수. 5XX 시리즈 코드는 함수 오류 및 제한 시간과 같은 서버 측 오류를 나타냅니다.
함수 URL은 다음과 같은 성능 지표도 지원합니다. `Average` 또는 `Max` 통계를 사용하여 이러한 지표를 볼 것을 권장합니다.
+ `UrlRequestLatency` – 함수 URL이 요청을 수신하는 시점부터 함수 URL이 응답을 반환하는 시점까지의 시간입니다.
이러한 각 호출 및 성능 지표는 다음 차원을 지원합니다.
+ `FunctionName` – 함수의 `$LATEST` 게시되지 않은 버전 또는 함수의 별칭에 할당된 함수 URL에 대한 집계 지표를 확인합니다. 예: `hello-world-function`.
+ `Resource` – 특정 함수 URL에 대한 지표를 확인합니다 함수 이름과 함수의 `$LATEST` 게시되지 않은 버전 또는 함수의 별칭 중 하나로 정의합니다. 예: `hello-world-function:$LATEST`.
+ `ExecutedVersion` – 실행된 버전을 기반으로 특정 함수 URL에 대한 지표를 확인합니다. 이 차원을 사용하여 주로 `$LATEST` 게시되지 않은 버전에 할당된 함수 URL을 추적할 수 있습니다.
# HTTP 요청을 사용하여 Lambda 함수를 간접 호출하는 메서드 선택
Lambda에 대한 많은 일반적인 사용 사례는 HTTP 요청을 사용하여 함수를 간접 호출하는 작업과 관련이 있습니다. 예를 들어 웹 애플리케이션이 브라우저 요청을 통해 함수를 간접적으로 호출하도록 할 수 있습니다. Lambda 함수를 사용하여 전체 REST API를 생성하거나, 모바일 앱에서 사용자 상호 작용을 처리하거나, HTTP 호출을 통해 외부 서비스의 데이터를 처리하거나, 사용자 지정 웹후크를 생성할 수도 있습니다.
다음 섹션에서는 HTTP를 통해 Lambda를 간접 호출할 때 선택하는 항목을 설명하고 특정 사용 사례에 맞는 올바른 결정을 내리는 데 도움이 되는 정보를 제공합니다.
## HTTP 간접 호출 메서드를 선택할 때 선택할 수 있는 항목은 무엇인가요?
Lambda는 HTTP 요청을 사용하여 함수를 간접 호출하는 두 가지 주요 방법인 [함수 URL](urls-configuration.md) 및 [API Gateway](services-apigateway.md)를 제공합니다. 이 두 옵션의 주요 차이는 다음과 같습니다.
+ **Lambda 함수 URL**에서는 Lambda 함수에 대한 간단한 직접 HTTP 엔드포인트를 제공합니다. 단순성과 비용 효율성에 최적화되어 있으며 HTTP를 통해 Lambda 함수를 공개할 수 있는 가장 빠른 경로를 제공합니다.
+ **API Gateway**는 완전한 기능을 갖춘 API 빌드를 위한 보다 고급 서비스입니다. API Gateway는 대규모로 프로덕션 API를 빌드 및 관리하는 데 최적화되어 있으며 보안, 모니터링 및 트래픽 관리를 위한 포괄적인 도구를 제공합니다.
## 권장 사항(요구 사항을 이미 알고 있는 경우)
요구 사항을 이미 명확히 알고 있는 경우 기본 권장 사항은 다음과 같습니다.
기본 인증 방법 및 요청/응답 처리만 필요하고 비용과 복잡성을 최소화하려는 간단한 애플리케이션 또는 프로토타이프 제작에는 **[함수 URL](urls-configuration.md)**을 사용하는 것이 좋습니다.
**[API게이트웨이](services-apigateway.md)**는 대규모 프로덕션 애플리케이션 또는 [OpenAPI 설명](https://www.openapis.org/) 지원, 인증 옵션 선택 항목, 사용자 지정 도메인 이름 또는 스로틀링, 캐싱, 요청/응답 변환을 포함한 다양한 요청/응답 처리와 같은 고급 기능이 필요한 경우에 더 적합한 선택 항목입니다.
## Lambda 함수를 간접 호출하는 방법을 선택할 때 고려할 사항
함수 URL 및 API Gateway 중에서 선택할 때는 다음 요소를 고려해야 합니다.
+ OAuth 또는 Amazon Cognito에서 사용자를 인증해야 하는지 여부와 같은 인증 요구 사항
+ 규모 조정 요구 사항 및 구현하려는 API의 복잡성
+ 요청 검증 및 요청/응답 형식 지정과 같은 고급 기능이 필요한지 여부
+ 모니터링 요구 사항
+ 비용 목표
이러한 요소를 이해하면 보안, 복잡성 및 비용 요구 사항의 균형을 가장 잘 맞추는 옵션을 선택할 수 있습니다.
다음은 두 옵션 간 주요 차이를 요약한 정보입니다.
### Authentication
+ **함수 URL**에서는 AWS Identity and Access Management(IAM)를 통해 기본 인증 옵션을 제공합니다. 엔드포인트를 퍼블릭(인증 없음) 또는 IAM 인증을 요구하도록 구성할 수 있습니다. IAM 인증을 사용하면 표준 AWS 자격 증명 또는 IAM 역할을 사용하여 액세스를 제어할 수 있습니다. 간단하게 설정할 수 있지만 이 접근 방식에서는 다른 인증 방법에 비해 제한된 옵션을 제공합니다.
+ **API Gateway**는 보다 포괄적인 인증 옵션에 대한 액세스를 제공합니다. IAM 인증 외에도 [Lambda 권한 부여자](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)(사용자 지정 인증 로직), [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) 사용자 풀 및 OAuth2.0 흐름을 사용할 수 있습니다. 이러한 유연성을 통해 서드파티 인증 제공업체, 토큰 기반 인증 및 다중 인증 등 복잡한 인증 체계를 구현할 수 있습니다.
### 요청/응답 처리
+ **함수 URL**에서는 기본 HTTP 요청 및 응답 처리를 제공합니다. 이때 표준 HTTP 메서드를 지원하며 기본 제공 교차 오리진 리소스 공유(CORS) 지원을 포함합니다. 기본적으로 JSON 페이로드 및 쿼리 파라미터를 처리할 수 있지만 요청 변환 또는 검증 기능은 제공하지 않습니다. 응답 처리도 마찬가지로 간단합니다. 클라이언트는 Lambda에서 반환하는 대로 정확히 Lambda 함수로부터 응답을 수신합니다.
+ **API Gateway**에서는 정교한 요청 및 응답 처리 기능을 제공합니다. 요청 검증기를 정의하고, 매핑 템플릿을 사용하여 요청 및 응답을 변환하며, 요청/응답 헤더를 설정하고, 응답 캐싱을 구현할 수 있습니다. 또한 API Gateway는 바이너리 페이로드 및 사용자 지정 도메인 이름을 지원하며 클라이언트에 도달하기 전에 응답을 수정할 수 있습니다. JSON 스키마를 사용하여 요청/응답 검증 및 변환을 위한 모델을 설정할 수 있습니다.
### 스케일링
+ **함수 URL**에서는 Lambda 함수의 동시성 제한에 따라 직접 조정하며 구성된 최대 동시성 제한까지 함수를 조정하여 트래픽 급증을 처리합니다. 제한에 도달하면 Lambda는 HTTP 429 응답과 함께 추가 요청에 응답합니다. 기본 제공 대기열 메커니즘이 없으므로 규모 조정 처리는 전적으로 Lambda 함수의 구성에 따라 달라집니다. 기본적으로 Lambda 함수는 AWS 리전당 동시 실행이 1,000개로 제한됩니다.
+ **API Gateway**에서는 Lambda의 자체 규모 조정 외에도 추가 규모 조정 기능을 제공합니다. 여기에는 기본 제공 요청 대기열 및 스로틀링 제어가 포함되어 있어 트래픽 급증을 보다 점진적으로 관리할 수 있습니다. API Gateway에서는 기본적으로 리전당 1초에 최대 10,000건의 요청을 처리할 수 있으며 버스트 용량에서는 1초에 5,000건의 요청을 처리할 수 있습니다. 또한 백엔드를 보호하기 위해 여러 수준(API, 단계 또는 방법)에서 요청을 스로틀링하는 도구를 제공합니다.
### 모니터링
+ **함수 URL**에서는 요청 수, 지연 시간 및 오류 비율을 포함하여 Amazon CloudWatch 지표를 통한 기본 모니터링을 제공합니다. 함수에 들어오는 원시 요청을 보여주는 표준 Lambda 지표 및 로그에 액세스할 수 있습니다. 이를 통해 핵심적인 운영 가시성을 제공하지만 지표는 주로 함수 실행에 중점을 둡니다.
+ **API Gateway**에서는 세부 지표, 로깅 및 추적 옵션을 포함한 포괄적인 모니터링 기능을 제공합니다. CloudWatch를 통해 API 직접 호출, 지연 시간, 오류 비율 및 캐시 적중/누락 비율을 모니터링할 수 있습니다. 또한 API Gateway는 분산 추적을 위해 AWS X-Ray와 통합되며 사용자 지정 가능한 로깅 형식을 제공합니다.
### 비용
+ **함수 URL**은 표준 Lambda 요금 모델을 따르므로, 함수 간접 호출 및 컴퓨팅 시간에 대한 비용만 지불하면 됩니다. URL 엔드포인트 자체에는 추가 요금이 부과되지 않습니다. 따라서 API Gateway의 추가 기능이 필요하지 않은 경우 간단한 API 또는 트래픽이 적은 애플리케이션에 비용 효율적인 선택이 됩니다.
+ **API Gateway**는 REST API에 대해 수신된 백만 개의 API 직접 호출 및 HTTP API에 대해 수신된 백만 개의 API 직접 호출을 포함하는 [프리 티어](https://aws.amazon.com/api-gateway/pricing/#Free_Tier)를 제공합니다. 프리 티어 이후에 API Gateway에서는 API 직접 호출, 데이터 전송 및 캐싱(활성화된 경우)에 대해 요금을 청구합니다. 자체 사용 사례의 비용을 파악하기 위해 API Gateway [요금 페이지](https://aws.amazon.com/api-gateway/pricing/)를 참조하세요.
### 기타 기능
+ **함수 URL**은 단순성과 직접적인 Lambda 통합을 위해 설계되었습니다. 여기에서는 HTTP 및 HTTPS 엔드포인트를 모두 지원하고, 기본 제공 CORS 지원을 제공하며, 듀얼 스택(IPv4 및 IPv6) 엔드포인트를 제공합니다. 고급 기능은 부족하지만 HTTP를 통해 Lambda 함수를 공개하는 빠르고 간단한 방법이 필요한 시나리오에서 적합합니다.
+ **API Gateway**에는 API 버전 관리, 단계 관리, 사용 계획을 위한 API 키, Swagger/OpenAPI에 관한 API 설명서, WebSocket API, VPC 내 프라이빗 API, 추가 보안을 위한 WAF 통합과 같은 많은 추가 기능이 포함되어 있습니다. 또한 카나리 배포, 테스트를 위한 모의 통합 및 Lambda 외 다른 AWS 서비스와의 통합을 지원합니다.
## Lambda 함수를 간접 호출할 메서드 선택
이제 Lambda 함수 URL 및 API Gateway 중 하나를 선택하는 기준과 이들 간의 주요 차이에 대해 알아보았으니, 요구 사항에 가장 적합한 옵션을 선택하고 다음 리소스를 사용하여 사용을 시작할 수 있습니다.
------
#### [ Function URLs ]
**다음 리소스를 사용하여 함수 URL 시작하기**
+ 자습서 [함수 URL을 사용하여 Lambda 함수 생성](urls-webhook-tutorial.md) 수행
+ 이 설명서의 [Lambda 함수 URL 생성 및 관리](urls-configuration.md) 장에서 함수 URL에 대해 자세히 알아보기
+ 다음을 수행하여 콘솔 내 안내식 자습서 **간단한 웹 앱 생성**을 시도해 보세요.
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 여세요.
1. 화면의 오른쪽 상단에 있는 아이콘을 선택하여 도움말 패널을 여세요.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/console_help_screenshot.png)
1. **자습서**를 선택하세요.
1. **간단한 웹 앱 생성**에서 **자습서 시작**을 선택하세요.
------
#### [ API Gateway ]
**다음 리소스를 사용하여 Lambda 및 API Gateway 시작하기**
+ 자습서 [API Gateway와 함께 Lambda 사용](services-apigateway-tutorial.md)에 따라 백엔드 Lambda 함수와 통합된 REST API를 생성합니다.
+ *Amazon API Gateway 개발자 안내서*의 다음 섹션에서 API Gateway가 제공하는 여러 API 유형에 대해 자세히 알아보세요.
+ [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html)
+ [API Gateway HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html)
+ [API Gateway WebSocket API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html)
+ *Amazon API Gateway 개발자 안내서*의 [자습서 및 워크숍](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-tutorials.html) 섹션에서 하나 이상의 예제를 시도해 보세요.
------
# 자습서: Lambda 함수 URL을 사용하여 웹후크 엔드포인트 생성
이 자습서에서는 Lambda 함수 URL을 생성하여 웹후크 엔드포인트를 구현합니다. 웹후크는 HTTP를 사용하여 애플리케이션 간에 데이터를 자동으로 전송하는 경량형 이벤트 기반 통신입니다. 웹후크를 사용하면 다른 시스템에서 발생하는 이벤트(예: 새 고객의 웹 사이트 가입, 결제 처리, 파일 업로드)에 대한 즉각적인 업데이트를 받을 수 있습니다.
Lambda를 활용하면 Lambda 함수 URL 또는 API Gateway를 사용하여 웹후크를 구현할 수 있습니다. 함수 URL은 고급 권한 부여 또는 요청 검증 같은 기능이 필요하지 않은 간단한 웹후크에 적합합니다.
**작은 정보**
특정한 사용 사례에 가장 적합한 방법을 잘 모르는 경우 [HTTP 요청을 사용하여 Lambda 함수를 간접 호출하는 메서드 선택](furls-http-invoke-decision.md) 섹션을 참조하세요.
## 사전 조건
이 자습서를 완료하려면 로컬 시스템에 Python(버전 3.8 이상) 또는 Node.js(버전 18 이상)가 설치되어 있어야 합니다.
HTTP 요청을 사용하여 엔드포인트를 테스트할 수 있도록 자습서에서는 [curl](https://curl.se/)을 사용합니다. 이는 다양한 네트워크 프로토콜을 사용하여 데이터를 전송하는 데 사용할 수 있는 명령줄 도구입니다. 아직 도구를 설치하지 않은 경우, 도구를 설치하는 방법을 알아보려면 [curl 설명서](https://curl.se/docs/install.html)를 참조하세요.
## Lambda 함수 생성
HTTP 요청이 웹후크 엔드포인트로 전송될 때 실행되는 Lambda 함수를 우선 생성합니다. 이 예제에서 전송 애플리케이션은 결제가 제출될 때마다 업데이트를 전송하며 결제 성공 여부를 HTTP 요청 본문에 표시합니다. Lambda 함수는 요청을 구문 분석하고 결제 상태에 따라 조치를 취합니다. 이 예제에서는 코드가 결제의 주문 ID만 인쇄하지만, 실제 애플리케이션에서는 주문을 데이터베이스에 추가하거나 알림을 전송할 수 있습니다.
또한 이 함수는 웹후크, 해시 기반 메시지 인증(HMAC)에 사용되는 가장 일반적인 인증 방법을 구현합니다. 이 방법을 사용하면 발신 및 수신 애플리케이션 두 가지 모두가 보안 키를 공유합니다. 전송 애플리케이션은 해싱 알고리즘을 사용하여 메시지 콘텐츠와 함께 이 키를 사용하여 고유한 서명을 생성하며, 웹후크 요청 내에 서명을 HTTP 헤더로 포함합니다. 그런 다음 수신 애플리케이션이 이 단계를 반복하여 보안 키를 사용해 서명을 생성하며, 결과 값을 요청 헤더에 전송된 서명과 비교합니다. 결과가 일치하면 요청이 정상적인 것으로 간주됩니다.
Python 또는 Node.js 런타임과 함께 Lambda 콘솔을 사용하여 함수를 생성합니다.
------
#### [ Python ]
**Lambda 함수 생성**
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 다음을 수행하여 기본 'Hello world' 함수를 생성합니다.
1. **함수 생성**을 선택합니다.
1. **새로 작성**을 선택합니다.
1. [**함수 이름**]에 **myLambdaWebhook**을 입력합니다.
1. **런타임**에서 **Python 3.14**을 선택합니다.
1. **함수 생성**을 선택합니다.
1. **코드 소스** 창에서 다음을 복사하고 붙여 넣어 기존 코드를 바꿉니다.
```
import json
import hmac
import hashlib
import os
def lambda_handler(event, context):
# Get the webhook secret from environment variables
webhook_secret = os.environ['WEBHOOK_SECRET']
# Verify the webhook signature
if not verify_signature(event, webhook_secret):
return {
'statusCode': 401,
'body': json.dumps({'error': 'Invalid signature'})
}
try:
# Parse the webhook payload
payload = json.loads(event['body'])
# Handle different event types
event_type = payload.get('type')
if event_type == 'payment.success':
# Handle successful payment
order_id = payload.get('orderId')
print(f"Processing successful payment for order {order_id}")
# Add your business logic here
# For example, update database, send notifications, etc.
elif event_type == 'payment.failed':
# Handle failed payment
order_id = payload.get('orderId')
print(f"Processing failed payment for order {order_id}")
# Add your business logic here
else:
print(f"Received unhandled event type: {event_type}")
# Return success response
return {
'statusCode': 200,
'body': json.dumps({'received': True})
}
except json.JSONDecodeError:
return {
'statusCode': 400,
'body': json.dumps({'error': 'Invalid JSON payload'})
}
except Exception as e:
print(f"Error processing webhook: {e}")
return {
'statusCode': 500,
'body': json.dumps({'error': 'Internal server error'})
}
def verify_signature(event, webhook_secret):
"""
Verify the webhook signature using HMAC
"""
try:
# Get the signature from headers
signature = event['headers'].get('x-webhook-signature')
if not signature:
print("Error: Missing webhook signature in headers")
return False
# Get the raw body (return an empty string if the body key doesn't exist)
body = event.get('body', '')
# Create HMAC using the secret key
expected_signature = hmac.new(
webhook_secret.encode('utf-8'),
body.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Compare the expected signature with the received signature to authenticate the message
is_valid = hmac.compare_digest(signature, expected_signature)
if not is_valid:
print(f"Error: Invalid signature. Received: {signature}, Expected: {expected_signature}")
return False
return True
except Exception as e:
print(f"Error verifying signature: {e}")
return False
```
1. **배포** 섹션에서 **배포**를 선택하여 함수의 코드를 업데이트하세요.
------
#### [ Node.js ]
**Lambda 함수 생성**
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 다음을 수행하여 기본 'Hello world' 함수를 생성합니다.
1. **함수 생성**을 선택합니다.
1. **새로 작성**을 선택합니다.
1. [**함수 이름**]에 **myLambdaWebhook**을 입력합니다.
1. **런타임**에서 **nodejs24.x**를 선택합니다.
1. **함수 생성**을 선택합니다.
1. **코드 소스** 창에서 다음을 복사하고 붙여 넣어 기존 코드를 바꿉니다.
```
import crypto from 'crypto';
export const handler = async (event, context) => {
// Get the webhook secret from environment variables
const webhookSecret = process.env.WEBHOOK_SECRET;
// Verify the webhook signature
if (!verifySignature(event, webhookSecret)) {
return {
statusCode: 401,
body: JSON.stringify({ error: 'Invalid signature' })
};
}
try {
// Parse the webhook payload
const payload = JSON.parse(event.body);
// Handle different event types
const eventType = payload.type;
switch (eventType) {
case 'payment.success': {
// Handle successful payment
const orderId = payload.orderId;
console.log(`Processing successful payment for order ${orderId}`);
// Add your business logic here
// For example, update database, send notifications, etc.
break;
}
case 'payment.failed': {
// Handle failed payment
const orderId = payload.orderId;
console.log(`Processing failed payment for order ${orderId}`);
// Add your business logic here
break;
}
default:
console.log(`Received unhandled event type: ${eventType}`);
}
// Return success response
return {
statusCode: 200,
body: JSON.stringify({ received: true })
};
} catch (error) {
if (error instanceof SyntaxError) {
// Handle JSON parsing errors
return {
statusCode: 400,
body: JSON.stringify({ error: 'Invalid JSON payload' })
};
}
// Handle all other errors
console.error('Error processing webhook:', error);
return {
statusCode: 500,
body: JSON.stringify({ error: 'Internal server error' })
};
}
};
// Verify the webhook signature using HMAC
const verifySignature = (event, webhookSecret) => {
try {
// Get the signature from headers
const signature = event.headers['x-webhook-signature'];
if (!signature) {
console.log('No signature found in headers:', event.headers);
return false;
}
// Get the raw body (return an empty string if the body key doesn't exist)
const body = event.body || '';
// Create HMAC using the secret key
const hmac = crypto.createHmac('sha256', webhookSecret);
const expectedSignature = hmac.update(body).digest('hex');
// Compare expected and received signatures
const isValid = signature === expectedSignature;
if (!isValid) {
console.log(`Invalid signature. Received: ${signature}, Expected: ${expectedSignature}`);
return false;
}
return true;
} catch (error) {
console.error('Error during signature verification:', error);
return false;
}
};
```
1. **배포** 섹션에서 **배포**를 선택하여 함수의 코드를 업데이트하세요.
------
## 보안 암호 키 생성
Lambda 함수는 웹후크 요청을 인증할 수 있도록 호출 애플리케이션과 공유하는 보안 키를 사용합니다. 이 예제에서는 키가 환경 변수에 저장됩니다. 프로덕션 애플리케이션에서는 함수 코드에 암호와 같은 민감한 정보를 저장하지 마십시오. 대신 [AWS Secrets Manager 보안 암호를 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)한 다음 [AWS Parameters and Secrets Lambda 확장](with-secrets-manager.md)을 사용하여 Lambda 함수에서 자격 증명을 검색합니다.
**웹후크 보안 암호 키 생성 및 저장**
1. 암호화 보안 난수 생성기를 사용하여 긴 무작위 문자열을 생성합니다. Python 또는 Node.js에서 다음 코드 조각을 사용하여 32자 보안 암호를 생성 및 인쇄하거나, 원하는 방법을 사용할 수 있습니다.
------
#### [ Python ]
**Example 보안 암호를 생성하는 코드**
```
import secrets
webhook_secret = secrets.token_urlsafe(32)
print(webhook_secret)
```
------
#### [ Node.js ]
**Example 보안 암호를 생성하는 코드(ES 모듈 형식)**
```
import crypto from 'crypto';
let webhookSecret = crypto.randomBytes(32).toString('base64');
console.log(webhookSecret)
```
------
1. 다음을 수행하여 생성된 문자열을 함수의 환경 변수로 저장합니다.
1. 함수에 대한 **구성** 페이지에서 **환경 변수**를 선택합니다.
1. **편집**을 선택합니다.
1. **Add environment variable(환경 변수 추가)**을 선택합니다.
1. **키**에서 **WEBHOOK\$1SECRET**을 입력한 다음, **값**에서 이전 단계에서 생성한 보안 암호를 입력합니다.
1. **저장**을 선택합니다.
자습서의 뒷부분에서 이 보안 암호를 다시 사용하여 함수를 테스트해야 하므로 이 보안 암호를 지금 메모해 두세요.
## 함수 URL 엔드포인트 생성
Lambda 함수 URL을 사용하여 웹후크의 엔드포인트를 생성합니다. 인증 유형 `NONE`을 사용하여 퍼블릭 액세스 권한이 있는 엔드포인트를 생성하면 URL이 있는 누구나 함수를 간접적으로 호출할 수 있습니다. 함수 URL에 대한 액세스 권한 제어를 자세히 알아보려면 [Lambda 함수 URL에 대한 액세스 제어](urls-auth.md) 섹션을 참조하세요. 웹후크에 대한 고급 인증 옵션이 필요한 경우 API Gateway를 사용하는 것이 좋습니다.
**함수 URL 엔드포인트 생성**
1. 함수의 **구성** 탭에서 **함수 URL**을 선택합니다.
1. **함수 URL 생성(Create function URL)**을 선택합니다.
1. **인증 유형**에서 **없음**을 선택합니다.
1. **저장**을 선택합니다.
방금 생성한 함수 URL의 엔드포인트가 **함수 URL** 창에 표시됩니다. 자습서의 뒷부분에서 사용할 엔드포인트를 복사합니다.
## 콘솔에서 함수 테스트
HTTP 요청을 사용하여 URL 엔드포인트를 사용하여 함수를 간접적으로 호출하려면 우선 콘솔에서 이를 테스트하여 코드가 예상대로 작동하는지 확인합니다.
콘솔에서 함수를 확인하려면 먼저 다음과 같은 테스트 JSON 페이로드를 통해 자습서 앞부분에서 생성한 보안 암호를 사용하여 웹후크 서명을 계산합니다.
```
{
"type": "payment.success",
"orderId": "1234",
"amount": "99.99"
}
```
다음과 같은 Python 또는 Node.js 코드 예제 중 하나를 사용해 고유한 보안 암호를 이용하여 웹후크 서명을 계산합니다.
------
#### [ Python ]
**웹후크 서명 계산**
1. 다음 코드를 `calculate_signature.py`라는 이름의 파일에 저장합니다. 코드의 웹후크 보안 암호를 원하는 고유한 값으로 바꿉니다.
```
import secrets
import hmac
import json
import hashlib
webhook_secret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M"
body = json.dumps({"type": "payment.success", "orderId": "1234", "amount": "99.99"})
signature = hmac.new(
webhook_secret.encode('utf-8'),
body.encode('utf-8'),
hashlib.sha256
).hexdigest()
print(signature)
```
1. 코드를 저장한 디렉터리에서 다음 명령을 실행하여 서명을 계산합니다. 코드가 출력하는 서명을 복사합니다.
```
python calculate_signature.py
```
------
#### [ Node.js ]
**웹후크 서명 계산**
1. 다음 코드를 `calculate_signature.mjs`라는 이름의 파일에 저장합니다. 코드의 웹후크 보안 암호를 원하는 고유한 값으로 바꿉니다.
```
import crypto from 'crypto';
const webhookSecret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M"
const body = "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}";
let hmac = crypto.createHmac('sha256', webhookSecret);
let signature = hmac.update(body).digest('hex');
console.log(signature);
```
1. 코드를 저장한 디렉터리에서 다음 명령을 실행하여 서명을 계산합니다. 코드가 출력하는 서명을 복사합니다.
```
node calculate_signature.mjs
```
------
이제 콘솔에서 테스트 HTTP 요청을 사용하여 함수 코드를 테스트할 수 있습니다.
**콘솔에서 함수 테스트**
1. 함수의 **코드** 탭을 선택합니다.
1. **테스트 이벤트** 섹션에서 **새로운 테스트 이벤트 생성**을 선택합니다.
1. **Event Name(이벤트 이름)**에 **myEvent**를 입력합니다.
1. 다음을 복사하여 **이벤트 JSON** 창에 붙여 넣어 기존 JSON을 바꿉니다. 웹후크 서명을 이전 단계에서 계산한 값으로 바꿉니다.
```
{
"headers": {
"Content-Type": "application/json",
"x-webhook-signature": "2d672e7a0423fab740fbc040e801d1241f2df32d2ffd8989617a599486553e2a"
},
"body": "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}"
}
```
1. **저장**을 선택합니다.
1. ** 간접 호출**를 선택합니다.
다음과 유사한 출력 화면이 표시되어야 합니다.
------
#### [ Python ]
```
Status: Succeeded
Test Event Name: myEvent
Response:
{
"statusCode": 200,
"body": "{\"received\": true}"
}
Function Logs:
START RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Version: $LATEST
Processing successful payment for order 1234
END RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6
REPORT RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Duration: 1.55 ms Billed Duration: 2 ms Memory Size: 128 MB Max Memory Used: 36 MB Init Duration: 136.32 ms
```
------
#### [ Node.js ]
```
Status: Succeeded
Test Event Name: myEvent
Response:
{
"statusCode": 200,
"body": "{\"received\":true}"
}
Function Logs:
START RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Version: $LATEST
2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234
END RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4
REPORT RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Duration: 60.10 ms Billed Duration: 61 ms Memory Size: 128 MB Max Memory Used: 72 MB Init Duration: 174.46 ms
Request ID: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4
```
------
## HTTP 요청을 사용하여 함수 테스트
curl 명령줄 도구를 사용하여 웹후크 엔드포인트를 테스트합니다.
**HTTP 요청을 사용하여 함수 테스트**
1. 터미널 또는 쉘 프로그램에서 다음 curl 명령을 실행합니다. URL을 고유한 함수 URL 엔드포인트의 값으로 바꾸고, 웹후크 서명을 고유한 보안 키를 사용하여 계산한 서명으로 바꿉니다.
```
curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \
-H "Content-Type: application/json" \
-H "x-webhook-signature: d5f52b76ffba65ff60ea73da67bdf1fc5825d4db56b5d3ffa0b64b7cb85ef48b" \
-d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}'
```
다음 결과가 표시됩니다.
```
{"received": true}
```
1. 함수의 CloudWatch 로그를 검사해 다음을 수행하여 페이로드를 올바르게 구문 분석했는지 확인합니다.
1. Amazon CloudWatch 콘솔에서 [로그 그룹](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 페이지를 엽니다.
1. 함수의 로그 그룹(`/aws/lambda/myLambdaWebhook`)을 선택합니다.
1. 최신 로그 스트림을 선택합니다.
함수의 로그에서 다음과 유사한 출력 화면이 표시되어야 합니다.
------
#### [ Python ]
```
Processing successful payment for order 1234
```
------
#### [ Node.js ]
```
2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234
```
------
1. 다음 curl 명령을 실행하여 코드가 잘못된 서명을 감지하는지 확인합니다. URL을 고유한 함수 URL 엔드포인트로 바꿉니다.
```
curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \
-H "Content-Type: application/json" \
-H "x-webhook-signature: abcdefg" \
-d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}'
```
다음 결과가 표시됩니다.
```
{"error": "Invalid signature"}
```
## 리소스 정리
이 자습서 용도로 생성한 리소스를 보관하고 싶지 않다면 지금 삭제할 수 있습니다. 더 이상 사용하지 않는 AWS 리소스를 삭제하면 AWS 계정에 불필요한 요금이 발생하는 것을 방지할 수 있습니다.
**Lambda 함수를 삭제하려면**
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 생성한 함수를 선택합니다.
1. **작업**(Actions), **삭제**(Delete)를 선택합니다.
1. 텍스트 입력 필드에 **confirm**를 입력하고 **Delete**(삭제)를 선택합니다.
콘솔에서 Lambda 함수를 생성하면 Lambda는 함수에 대한 [실행 역할](lambda-intro-execution-role.md)도 생성합니다.
**집행 역할 삭제**
1. IAM 콘솔에서 [역할 페이지](https://console.aws.amazon.com/iam/home#/roles)를 엽니다.
1. Lambda가 생성한 실행 역할을 선택합니다. 역할의 이름 형식은 `myLambdaWebhook-role-`입니다.
1. **삭제**를 선택합니다.
1. 텍스트 입력 필드에 역할의 이름을 입력하고 **Delete**(삭제)를 선택합니다.