이벤트 소스 매핑 생성 이벤트 소스 매핑 업데이트 이벤트 소스 매핑 삭제 일괄 처리 동작 이벤트 소스 매핑 간접 호출을 위한 대상 구성

Lambda 이벤트 소스 매핑

참고

Lambda 함수 이외의 대상으로 데이터를 전송하거나 데이터를 전송하기 전에 데이터를 보강하려는 경우 Amazon EventBridge 파이프를 참조하세요.

이벤트 소스 매핑은 이벤트 소스에서 읽어 Lambda 함수를 호출하는 Lambda 리소스입니다. 이벤트 소스 매핑을 사용해 Lambda 함수를 직접 호출하지 않는 서비스의 스트림 또는 대기열에서 항목을 처리할 수 있습니다. 이 페이지에서는 Lambda가 제공하는 이벤트 소스 매핑에 대해 설명하고 배치 처리 동작을 미세 조정하는 방법을 설명합니다.

Lambda가 이벤트를 읽는 서비스

이벤트 소스 매핑은 함수의 실행 역할에 있는 권한을 사용해 이벤트 소스의 항목을 읽고 관리합니다. 권한, 이벤트 구조, 설정 및 폴링 동작은 이벤트 소스에 따라 달라집니다. 자세한 내용은 이벤트 소스로 사용하는 서비스에 대해 링크된 주제를 참조하세요.

AWS Command Line Interface(AWS CLI) 또는 AWS SDK를 사용하여 이벤트 소스를 관리하려면 다음 API 작업을 사용할 수 있습니다.

주의

Lambda 이벤트 소스 매핑은 각 이벤트를 한 번 이상 처리하므로 일괄 처리가 중복될 수 있습니다. 중복 이벤트와 관련된 잠재적 문제를 방지하려면 함수 코드를 멱등성으로 만드는 것이 좋습니다. 자세한 내용은 AWS 지식 센터의 멱등성 Lambda 함수를 만들려면 어떻게 해야 합니까?를 참조하세요.

이벤트 소스 매핑 생성

이벤트 소스와 Lambda 함수 간 매핑을 생성하려면 콘솔에서 트리거를 생성하거나 create-event-source-mapping 명령을 사용합니다.

권한 추가 및 트리거 생성

실행 역할에 필요한 권한을 추가합니다. Amazon SQS와 같은 일부 서비스에는 Lambda가 이벤트 소스에서 읽어야 하는 권한이 포함된 AWS 관리형 정책이 있습니다.
Lambda 콘솔의 함수 페이지를 엽니다.
함수의 이름을 선택합니다.
함수 개요(Function overview)에서 트리거 추가(Add trigger)를 선택합니다.
트리거 유형을 선택합니다.
필요한 옵션을 구성한 다음 추가를 선택합니다.

이벤트 소스 매핑 생성(AWS CLI)

다음 예제는 AWS CLI를 사용하여 배치 크기가 500인 Amazon 리소스 이름(ARN)이 지정하는 DynamoDB 스트림에 my-function이라는 함수를 매핑합니다.


aws lambda create-event-source-mapping --function-name my-function --batch-size 500 --maximum-batching-window-in-seconds 5 --starting-position LATEST \
--event-source-arn arn:aws:dynamodb:us-east-2:123456789012:table/my-table/stream/2023-06-10T19:26:16.525

다음 결과가 표시됩니다.


{
    "UUID": "14e0db71-5d35-4eb5-b481-8945cf9d10c2",
    "BatchSize": 500,
    "MaximumBatchingWindowInSeconds": 5,
    "ParallelizationFactor": 1,
    "EventSourceArn": "arn:aws:dynamodb:us-east-2:123456789012:table/my-table/stream/2019-06-10T19:26:16.525",
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
    "LastModified": 1560209851.963,
    "LastProcessingResult": "No records processed",
    "State": "Creating",
    "StateTransitionReason": "User action",
    "DestinationConfig": {},
    "MaximumRecordAgeInSeconds": 604800,
    "BisectBatchOnFunctionError": false,
    "MaximumRetryAttempts": 10000
}

이벤트 소스 매핑 업데이트

이벤트 소스 매핑 업데이트(콘솔)

Lambda 콘솔의 함수 페이지를 엽니다.
함수를 선택합니다.
구성을 선택한 다음 트리거를 선택합니다.
트리거를 선택하고 편집을 선택합니다.

이벤트 소스 매핑 업데이트(AWS CLI)

update-event-source-mapping 명령을 사용합니다. 다음 예제에서는 Amazon SQS 이벤트 소스에 대한 최대 동시성을 구성합니다.


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --scaling-config '{"MaximumConcurrency":5}'

이벤트 소스 매핑 삭제

함수를 삭제해도 Lambda는 관련 이벤트 소스 매핑을 삭제하지 않습니다. 콘솔에서 또는 DeleteEventSourceMapping API 작업을 사용하여 이벤트 소스 매핑을 삭제할 수 있습니다.

이벤트 소스 매핑 삭제(콘솔)

Lambda 콘솔의 이벤트 소스 매핑 페이지를 엽니다.
삭제하려는 이벤트 소스 매핑을 선택합니다.
이벤트 소스 매핑 삭제 대화 상자에 delete를 입력한 후 삭제를 선택합니다.

이벤트 소스 매핑 삭제(AWS CLI)

delete-event-source-mapping 명령을 사용합니다.


aws lambda delete-event-source-mapping \
    --uuid a1b2c3d4-5678-90ab-cdef-11111EXAMPLE

일괄 처리 동작

이벤트 소스 매핑은 대상 이벤트 소스에서 항목을 읽습니다. 기본적으로 이벤트 소스 매핑은 레코드를 일괄 처리하고 Lambda는 이를 단일 페이로드로 함수에 전송합니다. 일괄 처리 동작을 미세 조정하려면 일괄 처리 기간(MaximumBatchingWindowInSeconds) 및 배치 크기(BatchSize)를 구성할 수 있습니다. 일괄 처리 기간은 레코드를 단일 페이로드로 수집할 최대 기간입니다. 배치 크기는 단일 배치의 최대 레코드 수입니다. Lambda는 다음 세 가지 기준 중 하나에 부합할 때 함수를 호출합니다.

일괄 처리 기간이 최댓값에 도달합니다. 기본 일괄 처리 기간 동작은 특정 이벤트 소스에 따라 다릅니다.
- Kinesis, DynamoDB 및 Amazon SQS 이벤트 소스의 경우: 기본 일괄 처리 기간은 0초입니다. 즉, Lambda는 배치 크기가 충족되거나 페이로드 크기 제한에 도달한 경우에만 함수로 배치를 전송합니다. 배치 작업 기간을 설정하려면 MaximumBatchingWindowInSeconds를 구성합니다. 이 파라미터를 0~300초 범위에서 초 단위로 설정할 수 있습니다. 일괄 처리 기간을 구성하는 경우, 이전 함수 간접 호출이 완료되는 즉시 다음 기간이 시작됩니다.
- Amazon MSK, 자체 관리형 Apache Kafka 및 Amazon MQ, Amazon DocumentDB 이벤트 소스의 경우 기본 일괄 처리 시간은 500ms입니다. MaximumBatchingWindowInSeconds는 0초에서 300초 사이의 값을 초 단위로 구성할 수 있습니다. 일괄 처리 기간은 첫 번째 레코드가 도착하는 즉시 시작됩니다.
  
  참고
  MaximumBatchingWindowInSeconds는 초 단위로만 변경할 수 있기 때문에 변경한 후에는 500ms 기본 일괄 처리 기간으로 되돌릴 수 없습니다. 기본 일괄 처리 기간을 복원하려면 새 이벤트 소스 매핑을 생성해야 합니다.
배치 크기가 충족됩니다. 최소 배치 크기는 1입니다. 기본 및 최대 배치 크기는 이벤트 소스에 따라 다릅니다. 이러한 값에 대한 자세한 내용은 CreateEventSourceMapping API 작업에 대한 BatchSize 사양을 참조하세요.
페이로드 크기가 6MB에 도달합니다. 이 한도는 수정할 수 없습니다.

다음 다이어그램은 이 세 가지 조건을 보여줍니다. 일괄 처리 기간이 t = 7초에서 시작한다고 가정합니다. 첫 번째 시나리오에서는 5개의 레코드를 누적한 후 일괄 처리 기간이 t = 47초로 2차 최댓값인 40에 도달합니다. 두 번째 시나리오에서는 일괄 처리 기간이 만료되기 전에 배치 크기가 10에 도달하므로 일괄 처리 기간이 일찍 종료됩니다. 세 번째 시나리오에서는 일괄 처리 기간이 만료되기 전에 최대 페이로드 크기에 도달하므로 일괄 처리 기간이 일찍 종료됩니다.

배치 기간은 일괄 처리 기간이 최댓값에 도달하거나 배치 크기가 충족되거나 페이로드 크기가 6MB에 도달하는 세 가지 기준 중 하나가 충족되면 만료됩니다.

다음 예제에서는 Kinesis 스트림에서 읽는 이벤트 소스 매핑을 보여줍니다. 이벤트 배치가 모든 처리 시도에 실패하면 이벤트 소스 매핑은 배치에 관한 세부 정보를 SQS 대기열로 보냅니다.

이벤트 소스 매핑은 Kinesis 스트림에서 읽기를 수행합니다. 레코드를 함수로 보내기 전에 로컬로 대기열에 저장합니다.

이벤트 배치는 Lambda가 함수에 보내는 이벤트입니다. 이것은 현재 일괄 처리 기간이 만료될 때까지 이벤트 소스 매핑이 읽는 항목에서 컴파일된 레코드 또는 메시지의 배치입니다.

Kinesis 및 DynamoDB 스트림의 경우 이벤트 소스 매핑은 스트림에 있는 각 샤드에 대해 반복기를 생성하고 각 샤드에 있는 항목을 순서대로 처리합니다. 이벤트 소스 매핑이 스트림에 표시되는 새 항목만 읽도록 또는 더 오래된 항목으로 시작하도록 구성할 수 있습니다. 처리된 항목은 스트림에서 제거되지 않으며 다른 함수 또는 소비자가 처리할 수 있습니다.

Lambda는 처리를 위해 다음 배치를 전송하기 전에 구성된 Lambda 확장이 완료될 때까지 기다리지 않습니다. 즉, Lambda가 다음 레코드 배치를 처리할 때 확장이 계속 실행될 수 있습니다. 이로 인해 계정의 동시성 설정 또는 제한을 위반하는 경우 제한 문제가 발생할 수 있습니다. 이것이 잠재적인 문제인지 여부를 탐지하려면 함수를 모니터링하고 이벤트 소스 매핑에 대해 예상보다 높은 동시성 지표가 표시되는지 확인하세요. 간접 호출 간격이 짧기 때문에 Lambda는 일시적으로 동시성 사용량을 샤드 수보다 더 높게 보고할 수 있습니다. 확장이 없는 Lambda 함수에서도 마찬가지입니다.

기본적으로, 함수가 오류를 반환하는 경우 함수가 성공할 때까지 또는 배치에 있는 항목이 만료될 때까지 전체 배치가 다시 처리됩니다. 순차적 처리를 위해 이벤트 소스 매핑은 오류가 해결될 때까지 영향을 받은 샤드에 대한 처리를 일시 중지합니다. 이전 이벤트를 무시하거나 여러 배치를 병렬로 처리하도록 이벤트 소스 매핑을 구성할 수 있습니다. 여러 배치를 병렬로 처리하는 경우에도 각 파티션 키에 대해 순차적 처리가 보장되지만 이벤트 소스 매핑은 동일한 샤드의 여러 파티션 키를 동시에 처리합니다.

스트림 소스(DynamoDB 및 Kinesis)의 경우, 함수에서 오류가 반환될 때 Lambda가 재시도하는 최대 횟수를 구성할 수 있습니다. 배치가 함수에 도달하지 않는 서비스 오류 또는 제한은 재시도 횟수에 반영되지 않습니다.

이벤트 배치를 무시할 때 호출 레코드를 다른 서비스로 보내도록 이벤트 소스 매핑을 구성할 수도 있습니다. Lambda는 이벤트 소스 매핑에 대해 다음 대상을 지원합니다.

Amazon SQS - SQS 대기열입니다.
Amazon SNS - SNS 주제입니다.

호출 레코드에는 JSON 형식의 실패한 이벤트 배치에 관한 세부 정보가 포함되어 있습니다.

다음 예제에서는 Kinesis 스트림의 호출 레코드를 보여 줍니다.

예 호출 레코드


{
    "requestContext": {
        "requestId": "c9b8fa9f-5a7f-xmpl-af9c-0c604cde93a5",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myfunction",
        "condition": "RetryAttemptsExhausted",
        "approximateInvokeCount": 1
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "version": "1.0",
    "timestamp": "2019-11-14T00:38:06.021Z",
    "KinesisBatchInfo": {
        "shardId": "shardId-000000000001",
        "startSequenceNumber": "49601189658422359378836298521827638475320189012309704722",
        "endSequenceNumber": "49601189658422359378836298522902373528957594348623495186",
        "approximateArrivalOfFirstRecord": "2019-11-14T00:38:04.835Z",
        "approximateArrivalOfLastRecord": "2019-11-14T00:38:05.580Z",
        "batchSize": 500,
        "streamArn": "arn:aws:kinesis:us-east-2:123456789012:stream/mystream"
    }
}

Lambda는 또한 FIFO(선입선출) 대기열에 대한 순차적 처리를 지원하므로 활성 메시지 그룹의 수까지 확장할 수 있습니다. 표준 대기열의 경우 항목이 반드시 순서대로 처리되지는 않습니다. Lambda는 최대한 빠르게 표준 대기열을 처리할 수 있도록 확장됩니다. 오류가 발생하면 Lambda는 배치를 개별 항목으로 대기열에 반환하고 원래 배치와 다른 그룹으로 처리할 수 있습니다. 때때로 이벤트 소스 매핑은 함수 오류가 발생하지 않았다 하더라도 대기열에서 동일한 항목을 두 번 수신할 수 있습니다. Lambda는 성공적으로 처리된 항목을 대기열에서 삭제합니다. Lambda가 항목을 처리할 수 없는 경우 항목을 DLQ(Dead Letter Queue) 또는 대상으로 전송하도록 소스 대기열을 구성할 수 있습니다.

Lambda 함수를 직접 호출하는 서비스에 대한 자세한 내용은 다른 서비스와 함께 AWS Lambda 사용를 참조하세요.

이벤트 소스 매핑 간접 호출을 위한 대상 구성

실패한 이벤트 소스 매핑 간접 호출 기록을 보관하려면 함수의 이벤트 소스 매핑에 대상을 추가합니다. 이벤트 소스 매핑 간접 호출의 대상 구성은 Kinesis, DynamoDB 및 Kafka 기반 이벤트 소스에서만 지원됩니다. 대상으로 전송되는 각 레코드는 간접 호출에 대한 세부 정보가 포함된 JSON 문서입니다. 오류 처리 설정과 마찬가지로 함수, 함수의 버전 또는 별칭에 대상을 구성할 수 있습니다.

참고

이벤트 소스 매핑 간접 호출의 경우 실패한 간접 호출에 대한 기록만 유지할 수 있습니다. 다른 비동기 간접 호출의 경우 성공한 간접 호출과 실패한 호출 모두에 대한 기록을 유지할 수 있습니다. 자세한 내용은 비동기식 호출에 대한 대상 구성 단원을 참조하십시오.

모든 Amazon SNS 주제 또는 Amazon SQS 대기열을 대상으로 구성할 수 있습니다. 이러한 대상 유형의 경우, Lambda는 레코드 메타데이터를 대상으로 전송합니다. Kafka 기반 이벤트 소스의 경우에만 Amazon S3 버킷을 대상으로 선택할 수도 있습니다. S3 버킷을 지정하면, Lambda는 메타데이터와 함께 전체 간접 호출 레코드를 대상으로 전송합니다.

아래 표는 이벤트 소스 매핑 간접 호출에 지원되는 대상 유형을 요약한 것입니다. Lambda가 선택한 목적지로 레코드를 성공적으로 전송하려면 함수의 실행 역할에도 관련 권한이 포함되어야 합니다. 또한 표에는 각 대상 유형이 JSON 간접 호출 레코드를 수신하는 방법도 설명되어 있습니다.

대상 유형	다음 이벤트 소스에서 지원	필요한 권한	대상별 JSON 형식
Amazon SQS 대기열	Kinesis DynamoDB 자체 관리형 Apache Kafka 및 관리형 Apache Kafka	sqs:SendMessage	Lambda는 간접 호출 레코드 메타데이터를 `Message`로 대상에 전달합니다.
Amazon SNS 주제	Kinesis DynamoDB 자체 관리형 Apache Kafka 및 관리형 Apache Kafka	sns:Publish	Lambda는 간접 호출 레코드 메타데이터를 `Message`로 대상에 전달합니다.
Amazon S3 버킷	자체 관리형 Apache Kafka 및 관리형 Apache Kafka	s3:PutObject s3:ListBuckets	Lambda는 간접 호출 레코드와 메타데이터와 함께 대상에 저장합니다.

다음 예는 실패한 Kinesis 이벤트 소스 간접 호출에 대해 Lambda가 SQS 대기열 또는 SNS 주제로 전송하는 내용을 보여줍니다. Lambda는 이러한 대상 유형에 대한 메타데이터만 전송하므로, streamArn, shardId, startSequenceNumber 및 endSequenceNumber 필드를 사용하여 전체 원본 레코드를 확보합니다.


{
    "requestContext": {
        "requestId": "c9b8fa9f-5a7f-xmpl-af9c-0c604cde93a5",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myfunction",
        "condition": "RetryAttemptsExhausted",
        "approximateInvokeCount": 1
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "version": "1.0",
    "timestamp": "2019-11-14T00:38:06.021Z",
    "KinesisBatchInfo": {
        "shardId": "shardId-000000000001",
        "startSequenceNumber": "49601189658422359378836298521827638475320189012309704722",
        "endSequenceNumber": "49601189658422359378836298522902373528957594348623495186",
        "approximateArrivalOfFirstRecord": "2019-11-14T00:38:04.835Z",
        "approximateArrivalOfLastRecord": "2019-11-14T00:38:05.580Z",
        "batchSize": 500,
        "streamArn": "arn:aws:kinesis:us-east-2:123456789012:stream/mystream"
    }
}

DynamoDB 이벤트 소스의 예는 오류 처리을 참조하세요. Kafka 이벤트 소스의 예는 자체 관리형 Apache Kafka에 대한 장애 시 대상 또는 Amazon MSK에 대한 장애 시 대상을 참조하십시오.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

비동기식 호출

이벤트 필터링