View a markdown version of this page

Estructura de mensaje de evento - Amazon Simple Storage Service
Mensajes de ejemplo

Estructura de mensaje de evento

El mensaje de notificación que Amazon S3 envía para publicar un evento está en formato JSON.

Para obtener información general e instrucciones sobre cómo configurar notificaciones de eventos, consulte Notificaciones de eventos de Amazon S3.

En este ejemplo se muestra versión 2.4 de la estructura JSON de notificación de eventos. A partir de la versión 2.4, Amazon S3 utiliza una única versión unificada para todos los tipos de eventos. Cada evento contiene información adicional específica de la operación. Anteriormente, Amazon S3 utilizaba la versión 2.1 para eventos generales, la versión 2.2 para los eventos de replicación entre regiones y la versión 2.3 para el ciclo de vida de S3, S3 Intelligent-Tiering, la ACL de objetos, el etiquetado de objetos y los eventos de eliminación de restauración de objetos.

Antes de la versión 2.4, los distintos tipos de eventos utilizaban versiones diferentes de la estructura de notificación de eventos (2.1, 2.2, 2.3). A partir de la versión 2.4, todos los tipos de eventos utilizan una única versión unificada. De ahora en adelante, la versión del evento se incrementará de manera coherente en todos los tipos de eventos a medida que el esquema evolucione.

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

Tenga en cuenta lo siguiente en relación con la estructura de mensajes de eventos:

  • El valor de clave eventVersion contiene una versión principal y una versión secundaria con el formato major.minor.

    La versión principal se incrementa si Amazon S3 realiza un cambio en la estructura del evento que no es compatible con versiones anteriores. Esto incluye eliminar un campo JSON existente o cambiar la forma en que se representa el contenido de un campo (por ejemplo: un formato de fecha).

    La versión secundaria se incrementa si Amazon S3 realiza un cambio en la estructura del evento que es compatible con versiones anteriores. Esto incluye agregar campos nuevos a la estructura del evento o ingresar nuevos tipos de eventos. Para mantener la compatibilidad con versiones secundarias nuevas de la estructura de eventos, recomendamos que las aplicaciones ignoren los campos nuevos.

    Para asegurarse de que las aplicaciones pueden analizar la estructura de eventos correctamente, le recomendamos que haga una comparación de igualdad con el número de la versión principal. Para asegurarse de que los campos previstos por la aplicación están presentes, también recomendamos realizar una comparación mayor o igual que con la versión secundaria.

  • El valor de la clave eventName hace referencia a la lista de tipos de notificaciones de eventos, pero no contiene el prefijo s3:.

  • El valor de la clave userIdentity hace referencia al identificador único del recurso de AWS Identity and Access Management (IAM) (un usuario, un rol, un grupo, etc.) que provocó el evento. Para obtener una definición de cada prefijo de identificación de IAM (por ejemplo, AIDA, AROA, AGPA) e información sobre cómo conseguir el identificador único, consulte Identificadores únicos en la Guía del usuario de IAM.

  • El valor de clave responseElements es útil si desea realizar el seguimiento de una solicitud con AWS Support. x-amz-request-id y x-amz-id-2 ayudan a Amazon S3 a rastrear una solicitud individual. Estos valores son los mismos que los que devuelve Amazon S3 en respuesta a la solicitud que inicia los eventos. Por lo tanto, puede utilizar estos valores para emparejar el evento con la solicitud.

  • El valor de la clave s3 proporciona información acerca del bucket y el objeto involucrados en el evento. El valor del nombre de la clave de objeto está codificado como URL. Por ejemplo, red flower.jpg se convierte en red+flower.jpg. (Amazon S3 devuelve “application/x-www-form-urlencoded“ como el tipo de contenido en la respuesta).

    El valor de la clave ownerIdentity corresponde al ID de cliente minorista de Amazon (Amazon.com) del propietario del bucket. Este valor de ID ya no se utiliza y solo se conserva por razones de compatibilidad con versiones anteriores.

  • El valor de la clave sequencer proporciona un forma de determinar la secuencia de los eventos. No se garantiza que las notificaciones de eventos lleguen en el mismo orden en que se produjeron los eventos. Sin embargo, las notificaciones de eventos que crean objetos (solicitudes PUT) y eliminan objetos contienen un sequencer. Puede usar este valor para determinar el orden de los eventos de una clave de objeto determinada.

    Si compara las cadenas de sequencer de dos notificaciones de eventos en la misma clave de objeto, la notificación del evento con el mayor valor hexadecimal de sequencer es el evento que se produjo más tarde. Si utiliza notificaciones de eventos para mantener otra base de datos u otro índice de los objetos de Amazon S3, le recomendamos que compare y almacene los valores de sequencer a medida que procesa cada notificación de evento.

    Tenga en cuenta lo siguiente:

    • No puede utilizar el valor de la clave sequencer para determinar el orden de los eventos en diferentes claves de objeto.

    • Las cadenas de sequencer pueden ser de diferentes longitudes. Por lo tanto, para comparar estos valores, primero debe agregar ceros a la izquierda del valor más corto y, a continuación, realizar una comparación lexicográfica.

  • El valor de la clave glacierEventData solo es visible para los eventos s3:ObjectRestore:Completed.

  • El valor de la clave restoreEventData contiene atributos relacionados con la solicitud de restauración.

  • El valor de la clave replicationEventData solo es visible para los eventos de replicación.

  • El valor de la clave intelligentTieringEventData solo es visible para los eventos de S3 Intelligent-Tiering.

  • El valor de la clave lifecycleEventData solo es visible para los eventos de transición del ciclo de vida de S3.

  • El valor de la clave objectAnnotation solo es visible para los eventos de anotación (ObjectAnnotation:Put y ObjectAnnotation:Delete). Contiene una matriz con la anotación name, size (solo eventos Put) y eTag (solo eventos Put).

  • Para los eventos ObjectCreated:Copy, el bloque object incluye un campo booleano hasObjectAnnotation que indica si el objeto copiado tiene anotaciones.

Mensajes de ejemplo

A continuación se muestran ejemplos de mensajes de notificación de eventos de Amazon S3.

Mensaje de prueba de Amazon S3

Después de configurar una notificación de evento en un bucket, Amazon S3 envía el siguiente mensaje de prueba.

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

El mensaje s3:TestEvent utiliza un formato diferente al de las notificaciones de eventos normales de S3. A diferencia de otras notificaciones de eventos que utilizan la estructura de la matriz de Records mostrada anteriormente, el evento de prueba utiliza un formato simplificado con campos directos. Al implementar la gestión de eventos, asegúrese de que su código pueda distinguir y gestionar correctamente ambos formatos de mensaje.

Mensaje de ejemplo cuando se crea un objeto mediante una solicitud PUT

El siguiente mensaje es un ejemplo de un mensaje que Amazon S3 envía para publicar un evento de s3:ObjectCreated:Put.

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