Struttura del messaggio di evento - Amazon Simple Storage Service
Messaggi di esempio

Struttura del messaggio di evento

Il messaggio di notifica inviato da Amazon S3 per pubblicare un evento è in formato JSON.

Per una panoramica generale e istruzioni sulla configurazione delle notifiche degli eventi, consulta Notifiche di eventi Amazon S3.

Questo esempio mostra la versione 2.1della struttura JSON di notifica degli eventi. Amazon S3 utilizza le versioni 2.1, 2.2 e 2.3 di questa struttura di eventi. Amazon S3 utilizza la versione 2.2 per le notifiche di eventi di replica tra Regioni. Utilizza la versione 2.3 per S3 Lifecycle, S3 Intelligent-Tiering, ACL di oggetti, assegnazione di tag di oggetti e ripristino oggetti per gli eventi di eliminazione. Queste versioni contengono informazioni aggiuntive specifiche per queste operazioni. Le versioni 2.2 e 2.3 sono altrimenti compatibili con la versione 2.1 che Amazon S3 utilizza attualmente per altri tipi di notifiche di eventi.

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

Notare quanto segue sulla struttura dei messaggi di evento:

  • Il valore della chiave eventVersion contiene una versione maggiore e minore nel formato major.minor.

    La versione principale viene incrementata se Amazon S3 apporta una modifica alla struttura dell'evento che non è compatibile con le versioni precedenti. Questo include la rimozione di un campo JSON che è già presente o la modifica del modo in cui i contenuti di un campo vengono rappresentati (ad esempio, un formato di data).

    La versione secondaria viene incrementata se Amazon S3 aggiunge nuovi campi alla struttura dell'evento. Questo può succedere se vengono fornite nuove informazioni per alcuni o tutti gli eventi esistenti. Questo può succedere anche se vengono fornite nuove informazioni solo per i tipi di eventi appena introdotti. Per mantenere la compatibilità con le nuove versioni secondarie della struttura degli eventi, è consigliabile che le applicazioni ignorino i nuovi campi.

    Se vengono introdotti nuovi tipi di eventi ma la struttura dell’evento rimane invariata, la versione dell’evento non cambia.

    Per fare in modo che le applicazioni analizzino correttamente la struttura dell'evento, è consigliabile eseguire un confronto "uguale a" sul numero della versione maggiore. Per fare in modo che i campi richiesti dall'applicazione siano presenti, è inoltre consigliabile eseguire un confronto "maggiore di o uguale a" sulla versione minore.

  • Il valore di chiave eventName fa riferimento all’elenco dei tipi di notifiche degli eventi ma non contiene il prefisso s3:.

  • Il valore di chiave userIdentity fa riferimento all’ID univoco della risorsa AWS Identity and Access Management (IAM) (utente, ruolo, gruppo e così via) che ha causato l’evento. Per la definizione di ciascun prefisso di identificazione IAM (ad esempio AIDA, AROA, AGPA) e per informazioni su come ottenere l’identificatore univoco, consulta Identificatori univoci nella Guida per l’utente IAM.

  • Il valore chiave responseElements è utile se si desidera tracciare una richiesta monitorandone l'avanzamento con Supporto AWS. Sia x-amz-request-id sia x-amz-id-2 aiutano Amazon S3 a tenere traccia di una singola richiesta. Questi valori corrispondono a quelli che Amazon S3 restituisce nella risposta alla richiesta che avvia gli eventi. Pertanto, è possibile utilizzare questi valori per abbinare l’evento alla richiesta.

  • Il valore di chiave s3 fornisce informazioni sul bucket e sull’oggetto coinvolto nell’evento. Il valore del nome della chiave dell'oggetto ha la codifica URL. Ad esempio red flower.jpg diventa red+flower.jpg. Amazon S3 restituisce “application/x-www-form-urlencoded” come tipo di contenuto nella risposta.

    Il valore di chiave ownerIdentity corrisponde all’ID del cliente di vendita al dettaglio Amazon (Amazon.com) del proprietario del bucket. Questo valore di ID non viene più utilizzato e viene mantenuto solo per motivi di compatibilità con le versioni precedenti.

  • Il valore di chiave sequencer fornisce un modo per stabilire la sequenza degli eventi. Non è garantito che le notifiche di eventi arrivino nello stesso ordine in cui avvengono gli eventi. Tuttavia, notifiche di eventi che creano oggetti (richieste PUT) ed eliminano oggetti contengono un sequencer. È possibile utilizzare questo valore per determinare l’ordine degli eventi per una specifica chiave dell’oggetto.

    Se si confrontano le stringhe sequencer da due notifiche eventi nella stessa chiave dell'oggetto, la notifica evento con il valore esadecimale sequencer più elevato è l'evento che è avvenuto per ultimo. Se si utilizzano notifiche di eventi per mantenere un database o un indice separato degli oggetti Amazon S3, è consigliabile confrontare e archiviare i valori sequencer man mano che la notifica di ciascun evento viene elaborata.

    Tieni presente quanto segue:

    • Il valore di chiave sequencer non può essere utilizzato per determinare l’ordine degli eventi su diverse chiavi degli oggetti.

    • Le stringhe sequencer possono essere di diversa lunghezza. Quindi, per confrontare questi valori, per prima cosa aggiungi gli zeri al valore più breve e poi esegui un confronto lessicografico.

  • Il valore di chiave glacierEventData è visibile solo per gli eventi s3:ObjectRestore:Completed.

  • Il valore di chiave restoreEventData contiene attributi correlati alla richiesta di ripristino.

  • Il valore di chiave replicationEventData è visibile solo per gli eventi di replica.

  • Il valore di chiave intelligentTieringEventData è visibile solo per gli eventi Piano intelligente S3.

  • Il valore di chiave lifecycleEventData è visibile solo per gli eventi di transizione del ciclo di vita S3.

Messaggi di esempio

Di seguito sono riportati alcuni esempi di messaggi di notifica degli eventi Amazon S3.

Messaggio di prova Amazon S3

Quando configuri una notifica di eventi in un bucket, Amazon S3 invia il messaggio di prova riportato di seguito.

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

Il messaggio s3:TestEvent utilizza un formato diverso rispetto alle normali notifiche degli eventi S3. A differenza di altre notifiche degli eventi che utilizzano la struttura dell’array Records mostrata in precedenza, l’evento di test utilizza un formato semplificato con campi diretti. Quando si implementa la gestione degli eventi, è necessario assicurarsi che il codice sia in grado di distinguere e gestire correttamente entrambi i formati di messaggio.

Messaggio di esempio quando un oggetto viene creato utilizzando una richiesta PUT

Quello che segue è un esempio di un messaggio inviato da Amazon S3 per pubblicare un evento 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"
            }
         }
      }
   ]
}