本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 事件訊息結構
<a name="notification-content-structure"></a>

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

如需設定事件通知的一般概觀和指示，請參閱 [Amazon S3 事件通知](EventNotifications.md)。

此範例顯示事件通知 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` 索引鍵值會參考[事件通知類型](https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html)的清單，但不會包含 `s3:` 字首。
+ `userIdentity` 索引鍵值參考造成事件的 AWS Identity and Access Management (IAM) 資源 （使用者、角色、群組等） 的唯一 ID。對於每個 IAM 識別碼字首 (例如 AIDA、AROA、AGPA) 的定義，以及關於如何取得唯一識別碼的資訊，請參閱《IAM 使用者指南》**中的[唯一識別碼](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html##identifiers-unique-ids)。
+ 如果您想要追蹤請求，則`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 生命週期轉換事件顯現。

## 範例訊息
<a name="notification-content-structure-examples"></a>

以下是 Amazon S3 事件通知訊息的範例。

**Amazon S3 測試訊息**  
您在儲存貯體上設定事件通知後，Amazon S3 會傳送下列測試訊息。

```
1. {  
2.    "Service":"Amazon S3",
3.    "Event":"s3:TestEvent",
4.    "Time":"2014-10-13T15:57:02.089Z",
5.    "Bucket":"amzn-s3-demo-bucket",
6.    "RequestId":"5582815E1AEA5ADF",
7.    "HostId":"8cLeGAmw098X5cv4Zkwcmo8vvZa3eH3eKxsPzbB9wrR+YstdA6Knx4Ip8EXAMPLE"
8. }
```

**注意**  
`s3:TestEvent` 訊息使用的格式與一般 S3 事件通知不同。與其他使用先前所示 `Records` 陣列結構的事件通知不同，測試事件會搭配使用簡化格式與直接欄位。實作事件處理時，請確定您的程式碼可以區分和正確處理這兩種訊息格式。

**使用 `PUT` 請求建立物件時的範例訊息**  
以下是 Amazon S3 傳送以發佈 `s3:ObjectCreated:Put` 事件的訊息範例。

```
 1. {  
 2.    "Records":[  
 3.       {  
 4.          "eventVersion":"2.1",
 5.          "eventSource":"aws:s3",
 6.          "awsRegion":"us-west-2",
 7.          "eventTime":"1970-01-01T00:00:00.000Z",
 8.          "eventName":"ObjectCreated:Put",
 9.          "userIdentity":{  
10.             "principalId":"AIDAJDPLRKLG7UEXAMPLE"
11.          },
12.          "requestParameters":{  
13.             "sourceIPAddress":"172.16.0.1"
14.          },
15.          "responseElements":{  
16.             "x-amz-request-id":"C3D13FE58DE4C810",
17.             "x-amz-id-2":"FMyUVURIY8/IgAtTv8xRjskZQpcIZ9KG4V5Wp6S7S/JRWeUWerMUE5JgHvANOjpD"
18.          },
19.          "s3":{  
20.             "s3SchemaVersion":"1.0",
21.             "configurationId":"testConfigRule",
22.             "bucket":{  
23.                "name":"amzn-s3-demo-bucket",
24.                "ownerIdentity":{  
25.                   "principalId":"A3NL1KOZZKExample"
26.                },
27.                "arn":"arn:aws:s3:::amzn-s3-demo-bucket"
28.             },
29.             "object":{  
30.                "key":"HappyFace.jpg",
31.                "size":1024,
32.                "eTag":"d41d8cd98f00b204e9800998ecf8427e",
33.                "versionId":"096fKKXTRTtl3on89fVO.nfljtsv6qko",
34.                "sequencer":"0055AED6DCD90281E5"
35.             }
36.          }
37.       }
38.    ]
39. }
```