EventBridge 이벤트 메시지 구조

EventBridge 이벤트 메시지 구조

Amazon S3가 이벤트를 게시하기 위해 보내는 알림 메시지는 JSON 형식이에요. Amazon S3가 이벤트를 Amazon EventBridge로 보낼 때는 다음 필드들이 존재해요.

출처: EventBridge event message structure

본문

• version – 현재 모든 이벤트에 대해 0(영)이에요. 이는 Amazon EventBridge 봉투(envelope) 필드로, 스키마 버전 관리에는 사용되지 않아요. 이벤트 스키마 버전 관리는 detail 필드의 event-version 필드를 참고하세요.
• id – 모든 이벤트에 대해 생성되는 UUID예요.
• detail-type – 전송되는 이벤트의 유형이에요. 이벤트 유형 목록은 EventBridge 사용을 참고하세요.
• source – 이벤트를 생성한 서비스를 식별해요.
• account – 버킷 소유자의 12자리 AWS 계정 ID예요.
• time – 이벤트가 발생한 시간이에요.
• region – 버킷의 AWS 리전을 식별해요.
• resources – 버킷의 Amazon 리소스 이름(ARN)을 포함하는 JSON 배열이에요.
• detail – 이벤트에 대한 정보를 포함하는 JSON 객체예요. 이 필드에 무엇이 포함될 수 있는지에 대한 자세한 내용은 이벤트 메시지 detail 필드를 참고하세요.

이벤트 메시지 구조 예제

다음은 Amazon EventBridge로 보낼 수 있는 Amazon S3 이벤트 알림 메시지 예제의 일부예요.

객체 생성(Object created)

{
  "version": "0",
  "id": "17793124-05d4-b198-2fde-7ededc63b103",
  "detail-type": "Object Created",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2021-11-12T00:00:00Z",
  "region": "ca-central-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1",
      "aws-generated-tags": {
        "aws:cloudformation:stack-id": "arn:aws:cloudformation:us-east-1:111122223333:stack/amzn-s3-demo-stack/51af3dc0-da77-11e4-872e-1234567db123",
        "aws:cloudformation:logical-id": "S3DemoBucket",
        "aws:cloudformation:stack-name": "amzn-s3-demo-stack"
      }
    },
    "object": {
      "key": "example-key",
      "size": 5,
      "etag": "b1946ac92492d2347c6235b4d2611184",
      "version-id": "IYV3p45BT0ac8hjHg1houSdS1a.Mro8e",
      "sequencer": "617f08299329d189"
    },
    "request-id": "N4N7GDK58NMKJ12R",
    "requester": "123456789012",
    "source-ip-address": "192.0.2.1",
    "reason": "PutObject"
  }
}

객체 삭제(DeleteObject 사용)

{
  "version": "0",
  "id": "2ee9cc15-d022-99ea-1fb8-1b1bac4850f9",
  "detail-type": "Object Deleted",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2021-11-12T00:00:00Z",
  "region": "ca-central-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "version-id": "1QW9g1Z99LUNbvaaYVpW9xDlOLU.qxgF",
      "sequencer": "617f0837b476e463"
    },
    "request-id": "0BH729840619AG5K",
    "requester": "123456789012",
    "source-ip-address": "192.0.2.1",
    "reason": "DeleteObject",
    "deletion-type": "Delete Marker Created"
  }
}

객체 삭제(생명주기 만료 사용)

{
  "version": "0",
  "id": "ad1de317-e409-eba2-9552-30113f8d88e3",
  "detail-type": "Object Deleted",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2021-11-12T00:00:00Z",
  "region": "ca-central-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "version-id": "mtB0cV.jejK63XkRNceanNMC.qXPWLeK",
      "sequencer": "617b398000000000"
    },
    "request-id": "20EB74C14654DC47",
    "requester": "s3.amazonaws.com",
    "reason": "Lifecycle Expiration",
    "deletion-type": "Delete Marker Created"
  }
}

객체 복원 완료

{
  "version": "0",
  "id": "6924de0d-13e2-6bbf-c0c1-b903b753565e",
  "detail-type": "Object Restore Completed",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2021-11-12T00:00:00Z",
  "region": "ca-central-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "size": 5,
      "etag": "b1946ac92492d2347c6235b4d2611184",
      "version-id": "KKsjUC1.6gIjqtvhfg5AdMI0eCePIiT3"
    },
    "request-id": "189F19CB7FB1B6A4",
    "requester": "s3.amazonaws.com",
    "restore-expiry-time": "2021-11-13T00:00:00Z",
    "source-storage-class": "GLACIER"
  }
}

객체 어노테이션 생성

{
  "version": "0",
  "id": "8c2bfa57-4a67-b2ea-c4e0-6d420ea3b3a6",
  "detail-type": "Object Annotation Created",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2025-03-15T00:00:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "etag": "b1946ac92492d2347c6235b4d2611184",
      "version-id": "IYV3p45BT0ac8hjHg1houSdS1a.Mro8e",
      "sequencer": "617f08299329d189"
    },
    "request-id": "4B4NGD358NMKJ12R",
    "requester": "123456789012",
    "source-ip-address": "192.0.2.1",
    "reason": "PutObjectAnnotation",
    "object-annotation": {
      "name": "my-annotation",
      "size": 24,
      "etag": "05df351ea190dffc26f55c74425b9d7a"
    }
  }
}

객체 어노테이션 제거

{
  "version": "0",
  "id": "a3d1bc94-5f82-c7e1-d290-7e531fb4c5b8",
  "detail-type": "Object Annotation Removed",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2025-03-15T00:00:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "etag": "b1946ac92492d2347c6235b4d2611184",
      "version-id": "IYV3p45BT0ac8hjHg1houSdS1a.Mro8e",
      "sequencer": "617f08299329d190"
    },
    "request-id": "7C5NGD358NMKJ34S",
    "requester": "123456789012",
    "source-ip-address": "192.0.2.1",
    "reason": "DeleteObjectAnnotation",
    "object-annotation": {
      "name": "my-annotation"
    }
  }
}

객체 보존 업데이트

{
  "version": "0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "detail-type": "Object Retention Updated",
  "source": "aws.s3",
  "account": "111122223333",
  "time": "2026-04-07T14:30:00Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:s3:::amzn-s3-demo-bucket1"
  ],
  "detail": {
    "version": "0",
    "event-version": "1.2",
    "bucket": {
      "name": "amzn-s3-demo-bucket1"
    },
    "object": {
      "key": "example-key",
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "version-id": "abc123",
      "sequencer": "0055AED6DCD90281E5"
    },
    "request-id": "C3D13FE58DE4C810",
    "requester": "111122223333",
    "source-ip-address": "192.0.2.1",
    "object-retention-event-data": {
      "mode": "COMPLIANCE",
      "retain-until-date": "2026-07-06T14:30:00Z",
      "event-hold": "ON",
      "event-hold-duration": {
        "days": 90
      }
    }
  }
}

이벤트 메시지 detail 필드

detail 필드는 이벤트에 대한 정보가 담긴 JSON 객체를 포함해요. detail 필드에는 다음 필드가 존재할 수 있어요.

• version – 현재 모든 이벤트에 대해 0(영)이에요.

• event-version – major.minor 형식(예: 1.1)의 이벤트 스키마 버전이에요. 메이저 버전은 Amazon S3가 이벤트 구조에 하위 호환되지 않는 변경을 하면 증가해요. 여기에는 이미 존재하는 JSON 필드를 제거하거나 필드 내용의 표현 방식(예: 날짜 형식)을 바꾸는 것이 포함돼요. 마이너 버전은 Amazon S3가 이벤트 구조에 하위 호환되는 변경을 하면 증가해요. 여기에는 이벤트 구조에 새 필드를 추가하거나 새 이벤트 유형을 도입하는 것이 포함돼요. 이벤트 구조의 새 마이너 버전과 호환되도록 애플리케이션이 새 필드를 무시할 것을 권장해요. 애플리케이션이 이벤트 구조를 올바르게 파싱하도록 메이저 버전 번호에 등호 비교를 수행할 것을 권장해요. 애플리케이션이 기대하는 필드가 존재하도록 마이너 버전에 크거나 같음 비교를 수행하는 것도 권장해요.

• bucket – 이벤트에 관여한 Amazon S3 버킷에 대한 정보예요.

• aws-generated-tags – AWS 서비스가 버킷에 연결한 태그예요. AWS 생성 태그가 버킷에 존재할 때만 존재해요. 이 필드는 교차 리전 복제 이벤트에는 존재하지 않아요.

• object – 이벤트에 관여한 Amazon S3 객체에 대한 정보예요.

• request-id – S3 응답의 요청 ID예요.

• requester – 요청자의 AWS 계정 ID 또는 AWS 서비스 프린시펄이에요.

• source-ip-address – S3 요청의 소스 IP 주소예요. S3 요청으로 트리거된 이벤트에서만 존재해요.

• reason – Object Created 이벤트의 경우 객체를 만드는 데 사용된 S3 API예요: PutObject, POST Object, CopyObject, 또는 CompleteMultipartUpload. Object Deleted 이벤트의 경우, S3 API 호출로 객체가 삭제되면 DeleteObject로, S3 Lifecycle 만료 규칙으로 객체가 삭제되면 Lifecycle Expiration으로 설정돼요. 자세한 내용은 객체 만료를 참고하세요.

• deletion-type – Object Deleted 이벤트의 경우, 버전 관리가 없는 객체가 삭제되거나 버전화된 객체가 영구 삭제되면 Permanently Deleted로 설정돼요. 버전화된 객체에 대해 삭제 마커가 생성되면 Delete Marker Created로 설정돼요. 자세한 내용은 버전 관리가 활성화된 버킷에서 객체 버전 삭제를 참고하세요.

  일부 객체 속성(etag, size 등)은 삭제 마커가 생성될 때만 존재해요.

• restore-expiry-time – Object Restore Completed 이벤트의 경우, 객체의 임시 복사본이 S3에서 삭제될 시간이에요. 자세한 내용은 아카이브된 객체 작업을 참고하세요.

• source-storage-class – Object Restore Initiated와 Object Restore Completed 이벤트의 경우, 복원 중인 객체의 스토리지 클래스예요. 자세한 내용은 아카이브된 객체 작업을 참고하세요.

• destination-storage-class – Object Storage Class Changed 이벤트의 경우, 객체의 새 스토리지 클래스예요. 자세한 내용은 Amazon S3 Lifecycle로 객체 전환을 참고하세요.

• destination-access-tier – Object Access Tier Changed 이벤트의 경우, 객체의 새 액세스 티어예요. 자세한 내용은 Amazon S3 Intelligent-Tiering으로 스토리지 비용 관리를 참고하세요.

• object-annotation – Object Annotation Created와 Object Annotation Removed 이벤트의 경우, detail 필드에 어노테이션에 대한 정보를 담은 object-annotation 필드가 포함돼요.

• has-object-annotation – reason이 CopyObject인 Object Created 이벤트의 경우, 객체 블록에 복사된 객체에 어노테이션이 있는지 나타내는 has-object-annotation 불리언 필드가 포함돼요.

• object-retention-event-data – Object Retention Updated 이벤트의 경우, 변경 후 객체의 Object Lock 보존 상태를 담은 블록이에요. 이 블록에는 다음 필드가 포함돼요.

  • mode – 변경 후 객체에 적용된 Object Lock 보존 모드예요: COMPLIANCE 또는 GOVERNANCE.
  • retain-until-date – 변경 후 객체가 보존되는 ISO-8601 형식의 날짜예요. 활성 이벤트 홀드가 있는 객체의 경우, 이는 Amazon S3가 이벤트를 처리할 때 동적으로 계산된 날짜예요.
  • event-hold – 변경 후 이벤트 홀드 상태예요: ON 또는 OFF. 이벤트 홀드 작업(홀드 설정·해제)에서만 존재해요.
  • event-hold-duration – { "days": N} 또는 { "years": N} 형식의 이벤트 홀드 기간이에요. 이벤트 홀드 기간이 설정되거나 수정될 때만 존재해요.

더 알아보기

• Amazon EventBridge 활성화
• Amazon EventBridge 매핑 및 문제 해결