Structure des messages d’événements - Amazon Simple Storage Service
Exemples de messages

Structure des messages d’événements

Le message de notification qu’envoie Amazon S3 pour publier un événement est au format JSON.

Pour obtenir une présentation générale et des instructions sur la configuration des notifications d’événement, consultez Notifications d’événements Amazon S3.

Cet exemple illustre la version 2.1 de la structure JSON de notification d'événement. Amazon S3 utilise les versions 2.1, 2.2 et 2.3 de cette structure d’événement. Amazon S3 utilise la version 2.2 pour les notifications d’événements de réplication entre Régions. Il utilise la version 2.3 pour le cycle de vie S3, S3 Intelligent-Tiering, la liste ACL d’objet, le balisage d’objets et les événements de suppression de restauration d’objets. Ces versions contiennent des informations supplémentaires spécifiques à ces opérations. Les versions 2.2 et 2.3 sont par ailleurs compatibles avec la version 2.1, qu’Amazon S3 utilise actuellement pour tous les autres types de notifications d’événements.

{  
   "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"
            }
         }
      }
   ]
}

Notez les éléments suivants à propos de la structure des messages d’événement :

  • La valeur de clé eventVersion contient une version majeure et une version mineure au format major.minor.

    La version majeure est incrémentée si Amazon S3 apporte à la structure de l’événement une modification qui n’est pas rétrocompatible. Cela inclut la suppression d’un champ JSON déjà présent ou la modification de la représentation du contenu d’un champ (par exemple, un format de date).

    La version mineure est incrémentée si Amazon S3 ajoute de nouveaux champs à la structure de l’événement. Cela peut se produire si de nouvelles informations sont fournies pour certains ou tous les événements existants. Cela peut également se produire si de nouvelles informations sont fournies sur les nouveaux types d’événements introduits. À des fins de compatibilité avec les nouvelles versions mineures de la structure des événements, nous vous recommandons d’ignorer les nouveaux champs dans vos applications.

    Si de nouveaux types d’événement sont introduits, mais que la structure de l’événement n’est pas modifiée, la version de l’événement ne change pas.

    Pour vous assurer que vos applications puissent analyser correctement la structure de l’événement, nous vous recommandons d’effectuer une comparaison égal à sur le numéro de version majeure. Pour vous assurer que les champs qui sont attendus par votre application sont présents, nous vous recommandons également d’effectuer une comparaison « supérieur ou égal à » sur le numéro de version mineure.

  • La valeur de la clé eventName fait référence à la liste des types de notifications d’événements, mais elle ne contient pas le préfixe s3:.

  • La valeur de la clé userIdentity fait référence à l’ID unique de la ressource AWS Identity and Access Management (IAM) (utilisateur, rôle, groupe, etc.) à l’origine de l’événement. Pour connaître la définition de chaque préfixe d’identification IAM (par exemple, AIDA, AROA, AGPA), consultez Identifiants uniques dans le Guide de l’utilisateur IAM.

  • La valeur de clé responseElements est utile si vous souhaitez tracer une demande via un suivi avec AWS Support. Les deux éléments x-amz-request-id et x-amz-id-2 aident Amazon S3 à suivre une demande individuelle. Ces valeurs sont identiques à celles renvoyées par Amazon S3 dans la réponse à la demande qui initie les événements. Vous pouvez donc utiliser ces valeurs pour faire correspondre l’événement à la demande.

  • La clé s3 fournit des informations sur l’objet et le compartiment concernés par l’événement. La valeur du nom de clé d’objet est codée en URL. Par exemple, red flower.jpg devient red+flower.jpg. (Amazon S3 renvoie « application/x-www-form-urlencoded » comme type de contenu dans la réponse.)

    La valeur de la clé ownerIdentity correspond à l’ID client Amazon Retail (Amazon.com) du propriétaire du compartiment. Cette valeur d’ID n’est plus utilisée et n’est conservée qu’à des fins de rétrocompatibilité.

  • La valeur de la clé sequencer permet de déterminer la séquence des événements. Les notifications d’événements n’arrivent pas nécessairement dans le même ordre dans lequel les événement se sont produits. Toutefois, les notifications d’événements qui créent des objets (demandes PUT) et suppriment des objets contiennent un sequencer. Vous pouvez utiliser cette valeur pour déterminer l’ordre dans lequel se sont produits les événements pour une clé d’objet donnée.

    Si vous comparez les chaînes sequencer provenant de deux notifications d’événements associées à la même clé d’objet, la notification d’événement qui présente la plus grande valeur sequencer hexadécimale correspond à l’événement le plus récent. Si vous utilisez des notifications d’événement pour gérer une base de données ou un index distincts de vos objets Amazon S3, nous vous recommandons de comparer et de stocker les valeurs sequencer à mesure que vous traitez les notifications associées à chaque événement.

    Remarques :

    • Vous ne pouvez pas utiliser la valeur de la clé sequencer pour déterminer l’ordre des événements associés à différentes clés d’objet.

    • La longueur des chaînes sequencer est variable. Pour comparer ces valeurs, commencez par ajouter des zéros à gauche de la valeur la plus courte, puis effectuez une comparaison lexicographique.

  • Seule la valeur de la clé glacierEventData est visible pour les événements s3:ObjectRestore:Completed.

  • La valeur de la clé restoreEventData contient des attributs qui sont liés à votre demande de restauration.

  • La valeur de la clé replicationEventData n’est visible que pour les événements de réplication.

  • La valeur de la clé intelligentTieringEventData n’est visible que pour les événements S3 Intelligent-Tiering.

  • La valeur de la clé lifecycleEventData n’est visible que pour les événements de transition S3 Lifecycle.

Exemples de messages

Voici des exemples de messages de notification d’événement Amazon S3.

Message de test Amazon S3

Une fois que vous avez configuré une notification d’événement pour un compartiment, Amazon S3 envoie le message de test suivant.

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

Le message s3:TestEvent utilise un autre format que celui des notifications d’événements S3 habituelles. Contrairement aux autres notifications d’événements qui utilisent la structure Records présentée précédemment, l’événement de test utilise un format simplifié avec des champs directs. Lors de la mise en œuvre de la gestion des événements, assurez-vous que votre code est capable de faire la distinction entre les deux formats de message et de les gérer correctement.

Exemple de message envoyé lorsqu’un objet est créé à l’aide d’une demande PUT

Le message suivant est un exemple de message envoyé par Amazon S3 pour publier un événement 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"
            }
         }
      }
   ]
}