이벤트 메시지 구조

이벤트 메시지 구조

Amazon S3가 이벤트를 게시하기 위해 보내는 알림 메시지는 JSON 형식이에요. 이벤트 알림 구성에 대한 일반적인 개요와 지침은 Amazon S3 이벤트 알림을 참고하세요.

출처: Event message structure

본문

이 예제는 이벤트 알림 JSON 구조의 버전 2.6을 보여줘요. 이전에는 Amazon S3가 이벤트 유형에 따라 서로 다른 버전을 사용했어요. 일반 이벤트는 버전 2.1, 교차 리전 복제 이벤트는 2.2, S3 Lifecycle·S3 Intelligent-Tiering·객체 ACL·객체 태그 지정·객체 복원 삭제 이벤트는 버전 2.3을 사용했어요. 버전 2.4부터 Amazon S3는 모든 이벤트 유형에 단일 통합 버전을 사용하며, 스키마가 진화할 때마다 모든 이벤트 유형에 걸쳐 버전이 일관되게 증가해요. 각 이벤트에는 작업에 특정한 추가 정보가 포함돼요.

이벤트 알림 메시지의 최대 크기는 64KB예요. Amazon SQS를 대상으로 사용할 때는 대기열의 MaximumMessageSize 속성을 최소 64KB로 설정할 것을 권장해요. 이벤트 알림이 대기열의 구성된 MaximumMessageSize를 초과하면 Amazon SQS가 알림을 거부하고 이벤트를 전달하지 않아요. 자세한 내용은 이벤트 알림 유형 및 대상을 참고하세요.

{
  "Records":[
    {
      "eventVersion":"2.6",
      "eventSource":"aws:s3",
      "awsRegion":"us-west-2",
      "eventTime":" The time, in ISO-8601 format (for example, 1970-01-01T00:00:00.000Z) when Amazon S3 finished processing the request ",
      "eventName":" The event type ",
      "userIdentity": {
        "principalId":" The unique ID of the IAM resource that caused the event "
      },
      "requestParameters": {
        "sourceIPAddress":" The IP address where the request came from "
      },
      "responseElements": {
        "x-amz-request-id":" The Amazon S3 generated request ID ",
        "x-amz-id-2":" The Amazon S3 host that processed the request "
      },
      "s3": {
        "s3SchemaVersion":"1.0",
        "configurationId":" The ID found in the bucket notification configuration ",
        "bucket": {
          "name":" The name of the bucket, for example, amzn-s3-demo-bucket ",
          "ownerIdentity": {
            "principalId":" The Amazon retail customer ID of the bucket owner "
          },
          "arn":" The bucket Amazon Resource Name (ARN) ",
          "awsGeneratedTags":" A map of tag key-value pairs generated by AWS services and attached to the bucket; only present when AWS generated tags exist on the bucket. This field is not present for cross-Region replication events "
        },
        "object": {
          "key":" The object key name ",
          "size":" The object size in bytes (as a number) ",
          "eTag":" The object entity tag (ETag) ",
          "versionId":" The object version if the bucket is versioning-enabled; null or not present if the bucket isn't versioning-enabled ",
          "sequencer": " A string representation of a hexadecimal value used to determine event sequence; only used with PUT and DELETE requests "
        }
      },
      "glacierEventData": {
        "restoreEventData": {
          "lifecycleRestorationExpiryTime":" The time, in ISO-8601 format (for example, 1970-01-01T00:00:00.000Z), when the temporary copy of the restored object expires ",
          "lifecycleRestoreStorageClass":" The source storage class for restored objects "
        }
      },
      "objectRetentionEventData": {
        "mode":" The Object Lock retention mode applied to the object: COMPLIANCE or GOVERNANCE ",
        "retainUntilDate":" The date, in ISO-8601 format, until which the object is retained ",
        "eventHold":" The event hold state after the change: ON or OFF; present for event-hold operations ",
        "eventHoldDuration":" The event hold duration after the change, as { "days": N} or { "years": N}. Present when an event hold duration is set or modified. "
      }
    }
  ]
}

이벤트 메시지 구조에 대해 다음을 기억하세요.

  • eventVersion 키 값에는 major.minor 형태의 메이저 버전과 마이너 버전이 포함돼요. 메이저 버전은 Amazon S3가 이벤트 구조에 하위 호환되지 않는 변경을 하면 증가해요. 여기에는 이미 존재하는 JSON 필드를 제거하거나 필드 내용의 표현 방식(예: 날짜 형식)을 바꾸는 것이 포함돼요. 마이너 버전은 Amazon S3가 이벤트 구조에 하위 호환되는 변경을 하면 증가해요. 여기에는 이벤트 구조에 새 필드를 추가하거나 새 이벤트 유형을 도입하는 것이 포함돼요. 이벤트 구조의 새 마이너 버전과 호환되도록 애플리케이션이 새 필드를 무시할 것을 권장해요. 애플리케이션이 이벤트 구조를 올바르게 파싱하도록 메이저 버전 번호에 대해 등호 비교를 수행하는 것을 권장해요. 애플리케이션이 기대하는 필드가 존재하도록 마이너 버전에 대해 크거나 같음 비교를 수행하는 것도 권장해요.
  • eventName 키 값은 이벤트 알림 유형 목록을 참조하지만 s3: 접두사를 포함하지 않아요.
  • userIdentity 키 값은 이벤트를 일으킨 AWS Identity and Access Management(IAM) 리소스(사용자, 역할, 그룹 등)의 고유 ID를 참조해요. 각 IAM 식별 접두사(예: AIDA, AROA, AGPA)의 정의와 고유 식별자를 얻는 방법은 IAM 사용 안내서의 고유 식별자를 참고하세요.
  • responseElements 키 값은 AWS Support에 문의해 요청을 추적하려 할 때 유용해요. x-amz-request-id와 x-amz-id-2 둘 다 Amazon S3가 개별 요청을 추적하는 데 도움을 줘요. 이 값들은 이벤트를 시작하는 요청에 대한 응답으로 Amazon S3가 반환하는 값과 같아요. 따라서 이 값들을 사용해 이벤트를 요청과 일치시킬 수 있어요.
  • s3 키 값은 이벤트에 관련된 버킷과 객체에 대한 정보를 제공해요. 객체 키 이름 값은 URL 인코딩돼 있어요. 예를 들어 red flower.jpg는 red+flower.jpg가 돼요. (Amazon S3는 응답에서 콘텐츠 유형을 "application/x-www-form-urlencoded"로 반환해요.)
  • ownerIdentity 키 값은 버킷 소유자의 Amazon 소매(Amazon.com) 고객 ID에 해당해요. 이 ID 값은 더 이상 사용되지 않으며 하위 호환성만을 위해 유지돼요.
  • sequencer 키 값은 이벤트의 순서를 결정하는 방법을 제공해요. 이벤트 알림은 이벤트가 발생한 순서와 같은 순서로 도착한다는 보장은 없어요. 그러나 객체를 생성하는 이벤트(PUT 요청)와 객체를 삭제하는 이벤트의 알림에는 sequencer가 포함돼 있어요. 이 값을 사용해 주어진 객체 키에 대한 이벤트 순서를 결정할 수 있어요. 같은 객체 키에 대한 두 이벤트 알림의 sequencer 문자열을 비교하면, sequencer 16진수 값이 더 큰 이벤트 알림이 더 나중에 발생한 이벤트예요. 이벤트 알림을 사용해 Amazon S3 객체의 별도 데이터베이스나 인덱스를 유지한다면, 각 이벤트 알림을 처리할 때 sequencer 값을 비교하고 저장할 것을 권장해요.
    • 다른 객체 키의 이벤트 순서를 결정하는 데 sequencer 키 값을 사용할 수 없어요.
    • sequencer 문자열은 길이가 다를 수 있어요. 따라서 이 값들을 비교하려면 먼저 더 짧은 값을 0으로 왼쪽 패딩한 다음 사전식 비교를 해야 해요.
  • glacierEventData 키 값은 s3:ObjectRestore:Completed 이벤트에서만 볼 수 있어요. restoreEventData 키 값에는 복원 요청과 관련된 속성이 포함돼 있어요.
  • replicationEventData 키 값은 복제 이벤트에서만 볼 수 있어요.
  • intelligentTieringEventData 키 값은 S3 Intelligent-Tiering 이벤트에서만 볼 수 있어요.
  • lifecycleEventData 키 값은 S3 Lifecycle 전환 이벤트에서만 볼 수 있어요.
  • objectAnnotation 키 값은 어노테이션 이벤트(ObjectAnnotation:Put과 ObjectAnnotation:Delete)에서만 볼 수 있어요. 어노테이션 name, size(Put 이벤트만), eTag(Put 이벤트만)를 가진 배열을 포함해요. ObjectCreated:Copy 이벤트의 경우 객체 블록에 복사된 객체에 어노테이션이 있는지 나타내는 hasObjectAnnotation 불리언 필드가 포함돼요.
  • objectRetentionEventData 키 값은 Object Lock 보존 이벤트(ObjectRetention:Put)에서만 볼 수 있어요. 변경 후 객체의 Object Lock 보존 상태를 포함해요. mode와 retainUntilDate 필드는 항상 존재해요. eventHold 필드(ON 또는 OFF)는 이벤트 홀드 작업에서 존재하고, eventHoldDuration은 이벤트 홀드 기간이 설정되거나 수정될 때 존재해요.

예제 메시지

다음은 Amazon S3 이벤트 알림 메시지 예제예요.

Amazon S3 테스트 메시지 – 버킷에 이벤트 알림을 구성한 뒤 Amazon S3가 다음 테스트 메시지를 보내요.

{
  "Service":"Amazon S3",
  "Event":"s3:TestEvent",
  "Time":"2014-10-13T15:57:02.089Z",
  "Bucket":" amzn-s3-demo-bucket ",
  "RequestId":"5582815E1AEA5ADF",
  "HostId":"8cLeGAmw098X5cv4Zkwcmo8vvZa3eH3eKxsPzbB9wrR+YstdA6Knx4Ip8EXAMPLE"
}

s3:TestEvent 메시지는 일반 S3 이벤트 알림과 다른 형식을 사용해요. 앞서 보여준 Records 배열 구조를 사용하는 다른 이벤트 알림과 달리, 테스트 이벤트는 직접 필드를 가진 단순화된 형식을 사용해요. 이벤트 처리를 구현할 때 코드가 두 메시지 형식을 구분하고 올바르게 처리할 수 있게 하세요.

PUT 요청으로 객체가 생성될 때의 예제 메시지 – 다음은 Amazon S3가 s3:ObjectCreated:Put 이벤트를 게시하기 위해 보내는 메시지 예제예요.

{
  "Records":[
    {
      "eventVersion":"2.6",
      "eventSource":"aws:s3",
      "awsRegion":"us-west-2",
      "eventTime":"1970-01-01T00:00:00.000Z",
      "eventName":"ObjectCreated:Put",
      "userIdentity": {
        "principalId":"AIDAJDPLRKLG7UEXAMPLE"
      },
      "requestParameters": {
        "sourceIPAddress":"172.16.0.1"
      },
      "responseElements": {
        "x-amz-request-id":"C3D13FE58DE4C810",
        "x-amz-id-2":"FMyUVURIY8/IgAtTv8xRjskZQpcIZ9KG4V5Wp6S7S/JRWeUWerMUE5JgHvANOjpD"
      },
      "s3": {
        "s3SchemaVersion":"1.0",
        "configurationId":"testConfigRule",
        "bucket": {
          "name":" amzn-s3-demo-bucket ",
          "ownerIdentity": {
            "principalId":"A3NL1KOZZKExample"
          },
          "arn":"arn:aws:s3::: amzn-s3-demo-bucket "
        },
        "object": {
          "key":"HappyFace.jpg",
          "size":1024,
          "eTag":"d41d8cd98f00b204e9800998ecf8427e",
          "versionId":"096fKKXTRTtl3on89fVO.nfljtsv6qko",
          "sequencer":"0055AED6DCD90281E5"
        }
      }
    }
  ]
}

더 알아보기