Lambda가 함수로 보내는 이벤트에 대한 제어

이벤트 필터링을 사용하여 Lambda가 함수로 전송하는 스트림 또는 대기열의 레코드를 제어할 수 있습니다. 예를 들어 함수에서 특정 데이터 파라미터가 포함된 Amazon SQS 메시지만 처리하도록 필터를 추가할 수 있습니다. 이벤트 필터링은 특정 이벤트 소스 매핑에서만 작동합니다. 다음 AWS 서비스에 대한 이벤트 소스 매핑에 필터를 추가할 수 있습니다.

특정 이벤트 소스를 사용한 필터링에 대한 자세한 내용은 서로 다른 AWS 서비스에서 필터 사용을 참조하세요. Lambda는 Amazon DocumentDB에 대한 이벤트 필터링을 지원하지 않습니다.

기본적으로 단일 이벤트 소스 매핑에 대해 최대 5개의 필터를 정의할 수 있습니다. 필터는 논리적으로 OR로 결합됩니다. 이벤트 소스의 레코드가 하나 이상의 필터를 충족하는 경우 Lambda는 함수로 전송하는 다음 이벤트에 해당 레코드를 포함합니다. 충족되는 필터가 없으면 Lambda는 레코드를 삭제합니다.

이벤트 필터링 기본 사항에 대한 이해

필터 기준(FilterCriteria) 객체는 필터(Filters) 목록으로 구성된 구조입니다. 각 필터는 이벤트 필터링 패턴(Pattern)을 정의하는 구조입니다. 패턴은 JSON 필터 규칙의 문자열 표현입니다. FilterCriteria 객체의 구조는 다음과 같습니다.

{
   "Filters": [
        {
            "Pattern": "{ \"Metadata1\": [ rule1 ], \"data\": { \"Data1\": [ rule2 ] }}"
        }
    ]
}

명확성을 더하기 위해 일반 JSON으로 확장된 필터의 Pattern 값은 다음과 같습니다.

{
    "Metadata1": [ rule1 ],
    "data": {
        "Data1": [ rule2 ]
    }
}

필터 패턴에는 메타데이터 속성, 데이터 속성 또는 둘 다 포함될 수 있습니다. 사용 가능한 메타데이터 파라미터와 데이터 파라미터의 형식은 이벤트 소스 역할을 하는 AWS 서비스에 따라 다릅니다. 예를 들어, 이벤트 소스 매핑이 Amazon SQS 대기열에서 다음 레코드를 수신한다고 가정해 보겠습니다.

{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "City": "Seattle",\n "State": "WA",\n "Temperature": "46"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
    },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
    "awsRegion": "us-east-2"
}

이벤트 소스 유형마다 데이터 필드에 서로 다른 키 값을 사용합니다. 데이터 속성을 필터링하려면 필터의 패턴에 올바른 키를 사용해야 합니다. 데이터 필터링 키 목록과 지원되는 각 AWS 서비스의 필터 패턴 예제는 서로 다른 AWS 서비스에서 필터 사용 섹션을 참조하세요.

이벤트 필터링은 멀티 레벨 JSON 필터링을 처리할 수 있습니다. 예를 들어 DynamoDB 스트림의 다음 레코드 조각을 고려하세요.

"dynamodb": {
    "Keys": {
        "ID": {
            "S": "ABCD"
        }
        "Number": {
            "N": "1234"
    },
    ...
}

정렬 키 Number의 값이 4567인 레코드만 처리하려고 한다고 가정해 보겠습니다. 이러한 경우 FilterCriteria 객체는 다음과 같습니다.

{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
        }
    ]
}

명확성을 더하기 위해 일반 JSON으로 확장된 필터의 Pattern 값은 다음과 같습니다.

{
    "dynamodb": {
        "Keys": {
            "Number": {
                "N": [ "4567" ]
                }
            }
        }
}

필터 기준을 충족하지 않는 레코드 처리

Lambda가 필터 기준을 충족하지 않는 레코드를 처리하는 방식은 이벤트 소스에 따라 다릅니다.

필터 규칙 구문

필터 규칙의 경우 Lambda는 Amazon EventBridge 규칙을 지원하며 EventBridge와 동일한 구문을 사용합니다. 자세한 내용은 Amazon EventBridge 사용 설명서의 Amazon EventBridge 이벤트 패턴을 참조하세요.

다음은 Lambda 이벤트 필터링에 사용할 수 있는 모든 비교 연산자에 대한 요약입니다.

Exists 연산자가 이벤트 소스 JSON의 리프 노드에서만 작동한다는 점에 유의하세요. 중간 노드와 일치하지 않습니다. 예를 들어 다음 JSON에서는 "address"가 중간 노드이므로 필터 패턴({ "person": { "address": [ { "exists": true } ] } }")이 일치하는 항목을 찾지 못합니다.

{
  "person": {
    "name": "John Doe",
    "age": 30,
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "country": "USA"
    }
  }
}

이벤트 소스 매핑에 필터 기준 연결(콘솔)

다음 단계에 따라 Lambda 콘솔을 사용하여 필터 기준을 사용하여 새 이벤트 소스 매핑을 생성합니다.

콘솔을 사용하여 필터 기준을 입력할 때 필터 패턴만 입력하면 되며 Pattern 키나 이스케이프 따옴표를 제공할 필요가 없습니다. 앞의 지침의 6단계에서 { "Metadata" : [ 1, 2 ] }는 다음 FilterCriteria에 해당합니다.

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

콘솔에서 이벤트 소스 매핑을 생성한 후 트리거 세부 정보에서 형식이 지정된 FilterCriteria를 확인할 수 있습니다. 콘솔을 사용하여 이벤트 필터를 생성하는 추가 예는 서로 다른 AWS 서비스에서 필터 사용 섹션을 참조하세요.

이벤트 소스 매핑에 필터 기준 연결(AWS CLI)

이벤트 소스 매핑에 다음 FilterCriteria가 포함되기를 원한다고 가정해 보겠습니다.

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

AWS Command Line Interface(AWS CLI)를 사용하여 이러한 필터 기준으로 새 이벤트 소스 매핑을 생성하려면 다음 명령을 실행합니다.

aws lambda create-event-source-mapping \
    --function-name my-function \
    --event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

이 create-event-source-mapping 명령은 지정된 FilterCriteria로 함수 my-function에 대한 새 Amazon SQS 이벤트 소스 매핑을 생성합니다.

이러한 필터 기준을 기존 이벤트 소스 매핑에 추가하려면 다음 명령을 실행합니다.

aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

이벤트 소스 매핑을 업데이트하려면 해당 UUID가 필요합니다. list-event-source-mappings 호출에서 UUID를 가져올 수 있습니다. Lambda는 또한 create-event-source-mapping CLI 응답에서 UUID를 반환합니다.

이벤트 소스에서 필터 기준을 제거하려면, 빈 FilterCriteria 객체로 다음 update-event-source-mapping 명령을 실행할 수 있습니다.

aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria "{}"

AWS CLI를 사용하여 이벤트 필터를 생성하는 추가 예는 서로 다른 AWS 서비스에서 필터 사용 섹션을 참조하세요.

이벤트 소스 매핑에 필터 기준 연결(AWS SAM)

AWS SAM에서 다음 필터 기준을 사용하도록 이벤트 소스를 구성한다고 가정해 보겠습니다.

{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

이러한 필터 기준을 이벤트 소스 매핑에 추가하려면 다음 코드 조각을 이벤트 소스의 YAML 템플릿에 삽입합니다.

FilterCriteria: 
  Filters: 
    - Pattern: '{"Metadata": [1, 2]}'

이벤트 소스 매핑을 위한 AWS SAM 템플릿을 생성하고 구성하는 방법에 대한 자세한 내용은 AWS SAM 개발자 가이드에서 EventSource 섹션을 참조하세요. AWS SAM 템플릿을 사용하여 이벤트 필터를 생성하는 추가 예는 서로 다른 AWS 서비스에서 필터 사용 섹션을 참조하세요.

필터 기준 암호화

기본적으로 Lambda는 필터 기준 객체를 암호화하지 않습니다. 필터 기준 객체에 민감한 정보를 포함할 수 있는 사용 사례의 경우 자체 KMS 키를 사용하여 이를 암호화할 수 있습니다.

필터 기준 객체를 암호화한 후 GetEventSourceMapping API 직접 호출을 사용하여 일반 텍스트 버전을 볼 수 있습니다. 필터 기준을 일반 텍스트로 제대로 볼 수 있으려면 kms:Decrypt 권한이 있어야 합니다.

콘솔, API/CLI 또는 AWS CloudFormation를 통해 고유한 KMS 키를 지정할 수 있습니다.

자체 KMS 키를 사용하는 경우 키 정책에서 다음 API 작업을 허용해야 합니다.

AWS CloudTrail을 사용하여 Lambda가 사용자 대신 수행하는 AWS KMS 요청을 추적할 수 있습니다. 샘플 CloudTrail 이벤트에 대한 내용은 Lambda에 대한 암호화 키 모니터링 섹션을 참조하세요.

또한 kms:ViaService 조건 키를 사용하여 KMS 키 사용을 Lambda의 요청으로만 제한하는 것이 좋습니다. 이 키의 값은 리전 Lambda 서비스 보안 주체(lambda.AWS_region.amazonaws.com)입니다. 다음은 모든 관련 권한을 부여하는 샘플 키 정책입니다.

{
    "Version": "2012-10-17",
    "Id": "example-key-policy-1",
    "Statement": [
        {
            "Sid": "Allow Lambda to decrypt using the key",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.us-east-1.amazonaws.com"
            },
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnEquals" : {
                    "aws:SourceArn": [
                        "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:<esm_uuid>"
                    ]
                },
                "StringEquals": {
                    "kms:EncryptionContext:aws:lambda:FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:test-function",
                    "kms:EncryptionContext:aws:lambda:EventSourceArn": "arn:aws:sqs:us-east-1:123456789012:test-queue"
                }
            }
        },
        {
            "Sid": "Allow actions by an AWS account on the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key to specific roles",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
            },
            "Action": [
                "kms:Decrypt",
                "kms:DescribeKey",
                "kms:GenerateDataKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals" : {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

자체 KMS 키를 사용하여 필터 기준을 암호화하려면 다음 CreateEventSourceMapping AWS CLI 명령을 사용할 수도 있습니다. --kms-key-arn 플래그를 사용하여 KMS 키 ARN을 지정합니다.

aws lambda create-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

기존 이벤트 소스 매핑이 있는 경우 UpdateEventSourceMapping AWS CLI 명령을 대신 사용하세요. --kms-key-arn 플래그를 사용하여 KMS 키 ARN을 지정합니다.

aws lambda update-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

이 작업은 이전에 지정된 모든 KMS 키를 덮어씁니다. 빈 인수와 함께 --kms-key-arn 플래그를 지정하면 Lambda는 KMS 키를 사용하여 필터 기준을 암호화하는 것을 중지합니다. 대신 Lambda는 기본적으로 Amazon 소유 키를 다시 사용합니다.

AWS CloudFormation 템플릿에서 고유한 KMS 키를 지정하려면 AWS::Lambda::EventSourceMapping 리소스 유형의 KMSKeyArn 속성을 사용하세요. 예를 들어 다음 코드 조각을 이벤트 소스의 YAML 템플릿에 삽입할 수 있습니다.

MyEventSourceMapping:
  Type: AWS::Lambda::EventSourceMapping
  Properties:
    ...
    FilterCriteria:
      Filters:
        - Pattern: '{"a": [1, 2]}'
    KMSKeyArn: "arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599"
    ...

GetEventSourceMapping 또는 DeleteEventSourceMapping API 직접 호출에서 암호화된 필터 기준을 일반 텍스트로 보려면 kms:Decrypt 권한이 있어야 합니다.

2024년 8월 6일부터 함수가 이벤트 필터링을 사용하지 않는 경우 CreateEventSourceMapping, UpdateEventSourceMapping 및 DeleteEventSourceMapping API 직접 호출의 AWS CloudTrail 로그에 FilterCriteria 필드가 더 이상 표시되지 않습니다. 함수가 이벤트 필터링을 사용하는 경우 {} 필드는 empty(FilterCriteria)로 표시됩니다. 올바른 KMS 키에 대한 kms:Decrypt 권한이 있으면 GetEventSourceMapping API 직접 호출의 응답에서 여전히 필터 기준을 일반 텍스트로 볼 수 있습니다.

{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AROA123456789EXAMPLE:userid1",
        "arn": "arn:aws:sts::123456789012:assumed-role/Example/example-role",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AROA987654321EXAMPLE",
                "arn": "arn:aws:iam::123456789012:role/User1",
                "accountId": "123456789012",
                "userName": "User1"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2024-05-09T20:35:01Z",
                "mfaAuthenticated": "false"
            }
        },
        "invokedBy": "AWS Internal"
    },
    "eventTime": "2024-05-09T21:05:41Z",
    "eventSource": "lambda.amazonaws.com",
    "eventName": "CreateEventSourceMapping20150331",
    "awsRegion": "us-east-2",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "requestParameters": {
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "functionName": "example-function",
        "enabled": true,
        "batchSize": 10,
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "scalingConfig": {},
        "maximumBatchingWindowInSeconds": 0,
        "sourceAccessConfigurations": []
    },
    "responseElements": {
        "uUID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
        "batchSize": 10,
        "maximumBatchingWindowInSeconds": 0,
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:example-function",
        "lastModified": "May 9, 2024, 9:05:41 PM",
        "state": "Creating",
        "stateTransitionReason": "USER_INITIATED",
        "functionResponseTypes": [],
        "eventSourceMappingArn": "arn:aws:lambda:us-east-2:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLEbbbbb"
    },
    "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
    "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}

서로 다른 AWS 서비스에서 필터 사용

이벤트 소스 유형마다 데이터 필드에 서로 다른 키 값을 사용합니다. 데이터 속성을 필터링하려면 필터의 패턴에 올바른 키를 사용해야 합니다. 다음 표에는 지원되는 각 AWS 서비스에 대한 필터링 키가 나와 있습니다.

다음 섹션들에서는 다양한 유형의 이벤트 소스에 대한 필터 패턴의 예제를 제공합니다. 또한 지원되는 수신 데이터 형식의 정의와 지원되는 각 서비스에 대한 필터 패턴 본문 형식을 제공합니다.