事件訊息結構 - Amazon Simple Storage Service
範例訊息

事件訊息結構

Amazon S3 傳送以發佈事件的通知訊息為 JSON 格式。

如需設定事件通知的一般概觀和指示，請參閱 Amazon S3 事件通知。

此範例顯示事件通知 JSON 結構的 2.1 版。Amazon S3 使用該事件結構的版本 2.1、2.2 和 2.3。Amazon S3 會將版本 2.2 用於跨區域複寫事件通知。它將版本 2.3 用於 S3 生命週期、S3 Intelligent-Tiering、物件 ACL、物件標記和物件還原刪除事件。這些版本包含特定於這些操作的額外資訊。版本 2.2 及 2.3 在其他方面與版本 2.1 相容，而 Amazon S3 目前可用於全部其他事件通知類型。

{  
   "Records":[  
      {  
         "eventVersion":"2.1",
         "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)"
            },
            "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"
            }
         }
      }
   ]
}

請注意，以下是事件訊息結構：

  • 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 支援 鍵值很有用。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 Retail (Amazon.com) 客戶 ID。此 ID 值不再使用，且只會為了回溯相容性而進行維護。

  • sequencer 索引鍵值提供判斷事件順序的方式。事件通知不保證按事件發生的相同順序抵達。不過，來自建立物件 (PUT 請求) 和刪除物件之事件的通知包含 sequencer。您可以使用此值來確定指定物件索引鍵的事件順序。

    如果比較 sequencer 字串和相同物件金鑰的兩項事件通知，sequencer 十六進位值較大的事件通知是發生較晚的事件。如果使用事件通知維護個別的 Amazon S3 物件資料庫或索引，則建議您在處理每項事件通知時，比較並存放 sequencer 值。

    注意下列事項：

    • 您不能使用 sequencer 索引鍵值來判斷不同物件索引鍵上的事件順序。

    • sequencer 字串長度可能各不相不同。所以，為了比較這些值，需先在較短值的左邊填充零，再執行字典排序比較。

  • 只有 s3:ObjectRestore:Completed 事件才可看見 glacierEventData 索引鍵值。

  • restoreEventData 索引鍵值包含與您的還原請求相關的屬性。

  • replicationEventData 索引鍵值只會對複寫事件顯現。

  • intelligentTieringEventData 索引鍵值只會對 S3 Intelligent-Tiering 事件顯現。

  • lifecycleEventData 索引鍵值只會對 S3 生命週期轉換事件顯現。

範例訊息

以下是 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.1",
         "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"
            }
         }
      }
   ]
}