# Lambda 비동기식 간접 호출 레코드 캡처
Lambda는 비동기식 간접 호출 레코드를 다음 중 하나로 전송할 수 있습니다. AWS 서비스
+ **Amazon SQS** - 표준 SQS 대기열
+ **Amazon SNS** - 표준 SNS 주제
+ **Amazon S3** - Amazon S3 버킷(실패한 경우에만)
+ **AWS Lambda** - Lambda 함수
+ **Amazon EventBridge** - EventBridge 이벤트 버스
호출 레코드에는 JSON 형식의 요청 및 응답에 대한 세부 정보가 포함되어 있습니다. 처리에 성공한 이벤트와 모든 처리 시도에서 실패한 이벤트에 대해 별도의 대상을 구성할 수 있습니다. 또는 삭제된 이벤트에 대해 표준 Amazon SQS 대기열 또는 표준 Amazon SNS 주제를 Dead Letter Queue(DLQ)로 구성할 수 있습니다. Dead Letter Queue(DLQ)의 경우 Lambda는 응답에 대한 세부 정보 없이 이벤트의 콘텐츠만 전송합니다.
Lambda에서 구성한 대상으로 레코드를 전송할 수 없는 경우 Amazon CloudWatch로 `DestinationDeliveryFailures` 지표를 전송합니다. 이는 구성에 Amazon SQS FIFO 대기열 또는 Amazon SNS FIFO 주제와 같이 지원되지 않는 대상 유형이 포함된 경우 발생할 수 있습니다. 전송 오류는 권한 오류 및 크기 제한으로 인해 발생할 수도 있습니다. Lambda 호출 지표에 대한 자세한 내용은 [호출 지표](monitoring-metrics-types.md#invocation-metrics)의 내용을 참조하세요.
**참고**
함수가 트리거되지 않도록 함수에 예약된 동시성을 0으로 설정할 수 있습니다. 비동기적으로 간접 호출된 함수에 대해 예약된 동시성을 0으로 설정하면 Lambda는 모든 이벤트를 구성된 [Dead Letter Queue(DLQ)](#invocation-dlq) 또는 실패 시 [이벤트 대상](#invocation-async-destinations)으로 새 이벤트를 보내기 시작합니다. 예약된 동시성이 0으로 설정된 상태에서 전송된 이벤트를 처리하려면 Dead Letter Queue(DLQ) 또는 실패 시 이벤트 대상에서 이벤트를 반드시 사용해야 합니다.
## 대상 추가
비동기식 간접 호출 레코드를 유지하려면 함수에 대상을 추가합니다. 성공한 또는 실패한 간접 호출을 대상으로 전송하도록 선택할 수 있습니다. 각 함수에는 여러 대상이 있을 수 있으므로 성공 및 실패한 이벤트에 대해 별도의 대상을 구성할 수 있습니다. 대상으로 전송되는 각 레코드는 간접 호출에 대한 세부 정보가 포함된 JSON 문서입니다. 오류 처리 설정과 마찬가지로 함수, 함수의 버전 또는 별칭에 대상을 구성할 수 있습니다.
**작은 정보**
[Amazon Kinesis](kinesis-on-failure-destination.md#kinesis-on-failure-destination-console), [Amazon DynamoDB](services-dynamodb-errors.md), [Apache Kafka(Amazon MSK 및 자체 관리형 Apache Kafka)](kafka-on-failure.md#kafka-onfailure-destination)와 같은 이벤트 소스 매핑 유형에 대해 실패한 간접 호출 기록을 유지할 수도 있습니다.
다음 표는 비동기식 간접 호출 레코드를 위해 지원되는 대상을 나열합니다. Lambda가 선택한 목적지로 레코드를 성공적으로 전송하려면 함수의 [실행 역할](lambda-intro-execution-role.md)에도 관련 권한이 포함되어야 합니다. 또한 표에는 각 대상 유형이 JSON 간접 호출 레코드를 수신하는 방법도 설명되어 있습니다.
| 대상 유형 | 필수 권한 | 대상별 JSON 형식 |
| --- | --- | --- |
| Amazon SQS 대기열 | [sqs:SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) | Lambda는 간접 호출 레코드를 `Message`로 목적지에 전달합니다. |
| Amazon SNS 주제 | [sns:Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) | Lambda는 간접 호출 레코드를 `Message`로 목적지에 전달합니다. |
| Amazon S3 버킷(실패한 경우에만) | [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) [s3:ListBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/invocation-async-retain-records.html) |
| Lambda 함수 | [lambda:InvokeFunction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Lambda는 간접 호출 레코드를 페이로드로 함수에 전달합니다. |
| EventBridge | [events:PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/invocation-async-retain-records.html) |
**참고**
Amazon S3 대상의 경우 KMS 키를 사용하여 버킷에서 암호화를 활성화하면 함수에 [kms:GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 권한도 필요합니다.
**중요**
Amazon SNS를 대상으로 사용하는 경우 Amazon SNS의 최대 메시지 크기 제한은 256KB입니다. 비동기식 간접 호출 페이로드가 1MB에 근접하면 간접 호출 레코드(원본 페이로드 및 추가 메타데이터 포함)가 Amazon SNS 제한을 초과하여 전송 실패를 일으킬 수 있습니다. 페이로드가 더 큰 경우에는 Amazon SQS 또는 Amazon S3 대상을 사용하는 것이 좋습니다.
다음 단계에서는 Lambda 콘솔과 AWS CLI를 사용하여 함수의 대상을 구성하는 방법을 설명합니다.
------
#### [ Console ]
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 함수를 선택합니다.
1. **함수 개요(Function overview)**에서 **대상 추가(Add destination)**를 선택합니다.
1. **소스**에서 **비동기식 간접 호출**을 선택합니다.
1. **Condition(조건)**에서 다음 옵션 중에 선택합니다.
+ **실패 시** – 이벤트가 모든 처리 시도에 실패하거나 최대 기간을 초과할 때 레코드를 전송합니다.
+ **성공 시** – 함수가 비동기식 간접 호출을 성공적으로 처리할 때 레코드를 전송합니다.
1. **Destination type(대상 유형)**에서 호출 레코드를 수신하는 리소스 유형을 선택합니다.
1. **Destination(대상)**에서 리소스를 선택합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
AWS CLI를 사용하여 대상을 구성하려면 [update-function-event-간접 호출-config](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-event-invoke-config.html) 명령을 실행합니다. 다음 예제에서는 이벤트를 처리할 수 없을 때 `destination`이라는 표준 SQS 대기열로 레코드를 전송하도록 Lambda를 구성합니다.
```
aws lambda update-function-event-invoke-config \
--function-name my-function \
--destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-1:123456789012:destination"}}'
```
------
### Amazon S3에 대한 보안 모범 사례
함수 구성에서 대상을 제거하지 않고 대상으로 구성된 S3 버킷을 삭제하면 보안 위험이 초래될 수 있습니다. 사용자의 대상 버킷 이름을 다른 사용자가 알고 있는 경우 AWS 계정에서 버킷을 다시 생성할 수 있습니다. 실패한 간접 호출에 대한 레코드가 해당 버킷으로 전송되어 함수의 데이터가 공개될 수 있습니다.
**주의**
함수의 간접 호출 레코드를 다른 AWS 계정의 S3 버킷으로 전송할 수 없도록 하려면 계정의 버킷에 대한 `s3:PutObject` 권한을 제한하는 조건을 함수의 실행 역할에 추가합니다.
다음 예제에서는 함수의 `s3:PutObject` 권한을 계정의 버킷으로 제한하는 IAM 정책을 보여줍니다. 또한 이 정책에서는 Lambda가 S3 버킷을 대상으로 사용하는 데 필요한 `s3:ListBucket` 권한도 부여합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3BucketResourceAccountWrite",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::*/*",
"arn:aws:s3:::*"
],
"Condition": {
"StringEquals": {
"s3:ResourceAccount": "111122223333"
}
}
}
]
}
```
AWS Management Console 또는 AWS CLI를 사용하여 함수의 실행 역할에 권한 정책을 추가하려면 다음 절차의 지침을 참조하세요.
------
#### [ Console ]
**함수의 실행 역할에 권한 정책을 추가하는 방법(콘솔)**
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 실행 역할을 수정하려는 Lambda 함수를 선택하세요.
1. **구성** 탭을 선택한 다음 **사용 권한**을 선택합니다.
1. **실행 역할** 탭에서 함수의 **역할 이름**을 선택하여 역할의 IAM 콘솔 페이지를 여세요.
1. 다음을 수행하여 역할에 기본 권한 정책을 추가하세요.
1. **권한** 창에서 **권한 추가**를 선택하고 **인라인 정책 생성**을 선택하세요.
1. **정책 편집기**에서 **JSON**을 선택하세요.
1. 추가하려는 정책을 편집기에 붙여넣고(이때 기존 JSON 대체) **다음**을 선택하세요.
1. **정책 세부 정보** 아래에 **정책 이름**을 입력하세요.
1. **정책 생성**을 선택합니다.
------
#### [ AWS CLI ]
**함수의 실행 역할에 권한 정책을 추가하는 방법(CLI)**
1. 필요한 권한이 있는 JSON 정책 문서를 생성하고 로컬 디렉터리에 저장하세요.
1. IAM `put-role-policy` CLI 명령을 사용하여 함수의 실행 역할에 권한을 추가하세요. JSON 정책 문서를 저장한 디렉터리에서 다음 명령을 실행하고 역할 이름, 정책 이름 및 정책 문서를 고유한 값으로 바꾸세요.
```
aws iam put-role-policy \
--role-name my_lambda_role \
--policy-name LambdaS3DestinationPolicy \
--policy-document file://my_policy.json
```
------
### 간접 호출 레코드 예제
호출이 조건과 일치하면 Lambda는 호출에 대한 세부 정보가 포함된 [JSON 문서](#destinations-permissions)를 대상으로 전송합니다. 다음 예제에서는 함수 오류로 인해 처리에 연속 3회 실패한 이벤트에 대한 호출 레코드를 보여 줍니다.
**Example**
```
{
"version": "1.0",
"timestamp": "2019-11-14T18:16:05.568Z",
"requestContext": {
"requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST",
"condition": "RetriesExhausted",
"approximateInvokeCount": 3
},
"requestPayload": {
"ORDER_IDS": [
"9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
"637de236-e7b2-464e-xmpl-baf57f86bb53",
"a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
]
},
"responseContext": {
"statusCode": 200,
"executedVersion": "$LATEST",
"functionError": "Unhandled"
},
"responsePayload": {
"errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
}
}
```
호출 레코드에는 이벤트, 응답 및 레코드가 전송된 이유에 대한 세부 정보가 포함되어 있습니다.
### 목적지로 향하는 요청 추적
AWS X-Ray을 사용하면 대기열에 추가되고, Lambda 함수에서 처리되고, 대상 서비스로 전달되는 각 요청의 연결된 보기를 볼 수 있습니다. 함수 또는 함수를 간접 호출하는 서비스에 대해 X-Ray 추적을 활성화하면 Lambda는 요청에 X-Ray 헤더를 추가하고 헤더를 대상 서비스에 전달합니다. 업스트림 서비스의 추적은 다운스트림 Lambda 함수 및 대상 서비스의 추적과 자동으로 연결되므로 전체 애플리케이션을 종합적으로 파악할 수 있습니다. 추적에 대한 자세한 내용은 [AWS X-Ray로 Lambda 함수 간접 호출 시각화](services-xray.md)의 내용을 참조하세요.
## Dead Letter Queue(DLQ) 추가
[on-failure 대상](#invocation-async-destinations)의 대안으로, 이후 처리를 위해 폐기된 이벤트를 저장하기 위해 Dead Letter Queue(DLQ)을 사용하여 함수를 구성할 수 있습니다. Dead Letter Queue(DLQ)은 이벤트가 모든 처리 시도에 실패하거나 처리되지 않고 만료될 때 사용된다는 점에서 on-failure 대상과 동일하게 작동합니다. 그러나 Dead Letter Queue(DLQ)는 함수 수준에서만 추가하거나 제거할 수 있습니다. 함수 버전은 게시되지 않은 버전(\$1LATEST)과 동일한 Dead Letter Queue(DLQ) 설정을 사용합니다. On-failure 대상은 추가 대상도 지원하며, 호출 레코드에 함수의 응답에 관한 세부 정보를 포함합니다.
Dead Letter Queue(DLQ)의 이벤트를 다시 처리하려면 Lambda 함수의 [이벤트 소스](invocation-eventsourcemapping.md)로 설정하면 됩니다. 또는 수동으로 이벤트를 검색할 수도 있습니다.
Dead Letter Queue(DLQ)에 대한 Amazon SQS 표준 대기열 또는 Amazon SNS 표준 주제를 선택할 수 있습니다. FIFO 대기열과 Amazon SNS FIFO 주제는 지원되지 않습니다.
+ [Amazon SQS 대기열](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-create-queue.html) – 대기열은 실패한 이벤트를 검색될 때까지 보관합니다. Lambda 함수 또는 CloudWatch 경보와 같은 단일 엔터티가 실패한 이벤트를 처리해야 하는 경우 Amazon SQS 표준 대기열을 선택합니다. 자세한 내용은 [Amazon SQS에서 Lambda 사용](with-sqs.md) 섹션을 참조하세요.
+ [Amazon SNS 주제](https://docs.aws.amazon.com/sns/latest/gsg/CreateTopic.html) – 주제는 실패한 이벤트를 한 개 이상의 대상으로 전달합니다. 실패한 이벤트에 대해 여러 엔터티가 작동할 것으로 예상되는 경우 Amazon SNS 표준 주제를 선택합니다. 예를 들어 이벤트를 이메일 주소, Lambda 함수 및/또는 HTTP 엔드포인트로 전송하도록 주제를 구성할 수 있습니다. 자세한 내용은 [Amazon SNS 알림을 사용하여 Lambda 함수 간접 호출](with-sns.md) 섹션을 참조하세요.
대기열 또는 주제로 이벤트를 전송하려면 함수에 추가 권한이 필요합니다. 함수의 [실행 역할](lambda-intro-execution-role.md)에 [필요한 권한](#destinations-permissions)이 있는 정책을 추가합니다. 대상 대기열 또는 주제가 고객 관리형 AWS KMS 키로 암호화된 경우 함수의 실행 역할과 키의 [리소스 기반 정책](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) 모두에 관련 권한이 포함되어 있는지 확인합니다.
대상을 생성하고 함수의 실행 역할을 업데이트한 후 Dead Letter Queue(DLQ)를 함수에 추가합니다. 여러 함수에서 동일한 대상으로 이벤트를 전송하도록 구성할 수 있습니다.
------
#### [ Console ]
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 함수를 선택합니다.
1. **구성**을 선택한 다음 **비동기식 간접 호출**을 선택합니다.
1. **비동기식 간접 호출**에서 **편집**을 선택합니다.
1. **Dead Letter Queue(DLQ) 서비스**를 **Amazon SQS** 또는 **Amazon SNS**로 설정합니다.
1. 대상 대기열 또는 주제를 선택합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
AWS CLI로 Dead Letter Queue(DLQ)를 구성하려면 [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) 명령을 사용합니다.
```
aws lambda update-function-configuration \
--function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-1:123456789012:my-topic
```
------
Lambda는 이벤트를 속성 관련 추가 정보와 함께 Dead Letter Queue(DLQ)에 있는 그대로 보냅니다. 이 정보를 사용해 함수가 반환한 오류를 식별하거나 이벤트와 로그 또는 AWS X-Ray 트레이스의 상관 관계를 알 수 있습니다.
**Dead Letter Queue(DLQ) 메시지 속성**
+ **RequestID**(문자열) – 호출 요청의 ID입니다. 요청 ID는 함수 로그에 표시됩니다. X-Ray SDK를 사용하여 트레이스의 속성에 대한 요청 ID를 기록할 수도 있습니다. 그런 다음 X-Ray 콘솔에서 요청 ID로 트레이스를 검색할 수 있습니다.
+ **ErrorCode**(숫자) – HTTP 상태 코드입니다.
+ **ErrorMessage**(문자열) – 오류 메시지의 첫 1KB입니다.
Lambda는 Dead Letter Queue(DLQ)로 메시지를 전송할 수 없는 경우 이벤트를 삭제하고 [DeadLetterErrors](monitoring-metrics-types.md) 지표를 내보냅니다. 이것은 권한이 없는 경우나 메시지 총 크기가 대상 대기열이나 주제의 한도를 초과하는 경우에 발생할 수 있습니다. 예를 들어 본문의 크기가 1MB에 가까운 Amazon SNS 알림이 함수를 트리거하여 오류가 발생한다고 가정합니다. 이 경우 Amazon SNS가 추가하는 이벤트 데이터가 Lambda가 추가하는 속성과 결합되어 메시지가 Dead Letter Queue(DLQ)에서 허용하는 최대 크기를 초과하게 될 수 있습니다.
Amazon SQS를 이벤트 소스로 사용하는 경우, Lambda 함수가 아닌 Amazon SQS 대기열 자체에 Dead Letter Queue(DLQ)를 구성합니다. 자세한 내용은 [Amazon SQS에서 Lambda 사용](with-sqs.md) 섹션을 참조하세요.