Trabaje con las notificaciones de eventos de S3

Para ayudarle a supervisar la actividad de sus buckets, Amazon S3 puede enviar notificaciones cuando se produzcan determinados eventos. La guía del usuario de Amazon S3 proporciona información sobre las notificaciones que puede enviar un bucket.

Para Java, puede configurar un depósito para enviar eventos a cuatro posibles destinos: SDK

• Temas de Amazon Simple Notification Service

• Colas de Amazon Simple Queue Service

• AWS Lambda funciones

• Amazon EventBridge

Cuando configuras un depósito al que enviar eventos EventBridge, tienes la posibilidad de configurar una EventBridge regla para distribuir el mismo evento a varios destinos. Al configurar el bucket para que se envíe directamente a uno de los tres primeros destinos, solo se puede especificar un tipo de destino para cada evento.

En la siguiente sección, verás cómo configurar un bucket con Java SDK para enviar notificaciones de eventos de S3 de dos maneras: directamente a una SQS cola de Amazon y a EventBridge.

En la última sección, se muestra cómo utilizar las notificaciones de eventos de S3 API para trabajar con las notificaciones de forma orientada a objetos.

Configure un bucket para enviarlo directamente a un destino

En el siguiente ejemplo, se configura un depósito para enviar notificaciones cuando se produzcan eventos de creación de objetos o de etiquetado de objetos en un depósito.

static void processS3Events(String bucketName, String queueArn) {
    // Configure the bucket to send Object Created and Object Tagging notifications to an existing SQS queue.
    s3Client.putBucketNotificationConfiguration(b -> b
            .notificationConfiguration(ncb -> ncb
                    .queueConfigurations(qcb -> qcb
                            .events(Event.S3_OBJECT_CREATED, Event.S3_OBJECT_TAGGING)
                            .queueArn(queueArn)))
                    .bucket(bucketName)
    );
}

El código que se muestra arriba configura una cola para recibir dos tipos de eventos. Convenientemente, el queueConfigurations método te permite configurar varios destinos de cola si es necesario. Además, en el notificationConfiguration método puede establecer destinos adicionales, como uno o más SNS temas de Amazon o una o más funciones de Lambda. En el siguiente fragmento se muestra un ejemplo con dos colas y tres tipos de destinos.

s3Client.putBucketNotificationConfiguration(b -> b
                .notificationConfiguration(ncb -> ncb
                        .queueConfigurations(qcb -> qcb
                                .events(Event.S3_OBJECT_CREATED, Event.S3_OBJECT_TAGGING)
                                .queueArn(queueArn), 
                                qcb2 -> qcb2.<...>)
                        .topicConfigurations(tcb -> tcb.<...>)
                        .lambdaFunctionConfigurations(lfcb -> lfcb.<...>))
                        .bucket(bucketName)
        );

El GitHub repositorio de ejemplos de código contiene el ejemplo completo para enviar notificaciones de eventos de S3 directamente a una cola.

Configure un bucket al que enviar EventBridge

En el siguiente ejemplo, se configura un depósito al que enviar EventBridge notificaciones.

public static String setBucketNotificationToEventBridge(String bucketName) {
    // Enable bucket to emit S3 Event notifications to EventBridge.
    s3Client.putBucketNotificationConfiguration(b -> b
            .bucket(bucketName)
            .notificationConfiguration(b1 -> b1
                    .eventBridgeConfiguration(SdkBuilder::build))
    .build());

Al configurar un depósito al que enviar eventos EventBridge, solo tiene que indicar el EventBridge destino, no los tipos de eventos ni el destino final al que EventBridge se enviarán. Los objetivos finales y los tipos de eventos se configuran mediante el EventBridge cliente SDK de Java.

El siguiente código muestra cómo configurar EventBridge para distribuir los eventos creados por objetos en un tema y una cola.

   public static String configureEventBridge(String topicArn, String queueArn) {
        try {
            // Create an EventBridge rule to route Object Created notifications.
            PutRuleRequest putRuleRequest = PutRuleRequest.builder()
                    .name(RULE_NAME)
                    .eventPattern("""
                            {
                              "source": ["aws.s3"],
                              "detail-type": ["Object Created"],
                              "detail": {
                                "bucket": {
                                  "name": ["%s"]
                                }
                              }
                            }
                            """.formatted(bucketName))
                    .build();

            // Add the rule to the default event bus.
            PutRuleResponse putRuleResponse = eventBridgeClient.putRule(putRuleRequest)
                    .whenComplete((r, t) -> {
                        if (t != null) {
                            logger.error("Error creating event bus rule: " + t.getMessage(), t);
                            throw new RuntimeException(t.getCause().getMessage(), t);
                        }
                        logger.info("Event bus rule creation request sent successfully. ARN is: {}", r.ruleArn());
                    }).join();

            // Add the existing SNS topic and SQS queue as targets to the rule.
            eventBridgeClient.putTargets(b -> b
                    .eventBusName("default")
                    .rule(RULE_NAME)
                    .targets(List.of (
                            Target.builder()
                                    .arn(queueArn)
                                    .id("Queue")
                                    .build(),
                            Target.builder()
                                    .arn(topicArn)
                                    .id("Topic")
                                    .build())
                            )
                    ).join();
            return putRuleResponse.ruleArn();
        } catch (S3Exception e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return null;
    }

Para trabajar con él EventBridge en tu código Java, añade una dependencia del eventbridge artefacto a tu archivo pom.xml Maven.

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>eventbridge</artifactId>
</dependency>

El GitHub repositorio de ejemplos de código contiene el ejemplo completo para enviar notificaciones de eventos de S3 a un tema EventBridge y una cola y, posteriormente, a ellos.

Utilice las notificaciones de eventos de S3 API para procesar los eventos

Una vez que un destino recibe los eventos de notificación de S3, puede procesarlos de forma orientada a objetos mediante las notificaciones de eventos de S3. API Puede utilizar las notificaciones de eventos de S3 API para trabajar con las notificaciones de eventos que se envían directamente a un destino (como se muestra en el primer ejemplo), pero no con las notificaciones que se envían directamente. EventBridge Las notificaciones de eventos de S3 se envían mediante buckets para EventBridge contener una estructura diferente que las notificaciones de eventos de S3 API no gestionan actualmente.

Añada dependencia

Las notificaciones de eventos de S3 API se publicaron con la versión 2.25.11 de la versión 2.x SDK para Java.

Para usar las notificaciones de eventos de S3API, agrega el elemento de dependencia necesario a tu Maven, pom.xml como se muestra en el siguiente fragmento.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.X.X1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3-event-notifications</artifactId>
    </dependency>
</dependencies>

^{1 Última versión}.

Usa la S3EventNotification clase

Crea una S3EventNotification instancia a partir de una JSON cadena

Para convertir una JSON cadena en un S3EventNotification objeto, usa los métodos estáticos de la S3EventNotification clase, como se muestra en el siguiente ejemplo.

import software.amazon.awssdk.eventnotifications.s3.model.S3EventNotification
import software.amazon.awssdk.eventnotifications.s3.model.S3EventNotificationRecord
import software.amazon.awssdk.services.sqs.model.Message; 

public class S3EventNotificationExample {
    ...
    
    void receiveMessage(Message message) {
       // Message received from SQSClient.
       String sqsEventBody = message.body();
       S3EventNotification s3EventNotification = S3EventNotification.fromJson(sqsEventBody);
    
       // Use getRecords() to access all the records in the notification.                                                                                                       
       List<S3EventNotificationRecord> records = s3EventNotification.getRecords();   
    
        S3EventNotificationRecord record = records.stream().findFirst();
        // Use getters on the record to access individual attributes.
        String awsRegion = record.getAwsRegion();
        String eventName = record.getEventName();
        String eventSource = record.getEventSource();                                                                                                   
    }
}

En este ejemplo, el fromJson método convierte la JSON cadena en un S3EventNotification objeto. La ausencia de campos en la JSON cadena generará null valores en los campos de objetos Java correspondientes y se JSON ignorará cualquier campo adicional que contenga.

En la API referencia APIs para un registro de notificación de eventos se encuentran otros registros de notificaciones de eventosS3EventNotificationRecord.

Convierte una S3EventNotification instancia en una JSON cadena

Usa el método toJson (ortoJsonPretty) para convertir un S3EventNotification objeto en una JSON cadena, como se muestra en el siguiente ejemplo.

import software.amazon.awssdk.eventnotifications.s3.model.S3EventNotification

public class S3EventNotificationExample {
    ...

    void toJsonString(S3EventNotification event) {

        String json = event.toJson();
        String jsonPretty = event.toJsonPretty();

        System.out.println("JSON: " + json);
        System.out.println("Pretty JSON: " + jsonPretty);
    }
}

Los campos GlacierEventData correspondientes aReplicationEventData,IntelligentTieringEventData, y LifecycleEventData se excluyen del campo JSON si lo estánnull. nullLos demás campos se serializarán comonull.

A continuación, se muestra un ejemplo del resultado del toJsonPretty método para un evento de etiquetado de objetos de S3.

{
  "Records" : [ {
    "eventVersion" : "2.3",
    "eventSource" : "aws:s3",
    "awsRegion" : "us-east-1",
    "eventTime" : "2024-07-19T20:09:18.551Z",
    "eventName" : "ObjectTagging:Put",
    "userIdentity" : {
      "principalId" : "AWS:XXXXXXXXXXX"
    },
    "requestParameters" : {
      "sourceIPAddress" : "XXX.XX.XX.XX"
    },
    "responseElements" : {
      "x-amz-request-id" : "XXXXXXXXXXXX",
      "x-amz-id-2" : "XXXXXXXXXXXXX"
    },
    "s3" : {
      "s3SchemaVersion" : "1.0",
      "configurationId" : "XXXXXXXXXXXXX",
      "bucket" : {
        "name" : "DOC-EXAMPLE-BUCKET",
        "ownerIdentity" : {
          "principalId" : "XXXXXXXXXXX"
        },
        "arn" : "arn:aws:s3:::XXXXXXXXXX"
      },
      "object" : {
        "key" : "akey",
        "size" : null,
        "eTag" : "XXXXXXXXXX",
        "versionId" : null,
        "sequencer" : null
      }
    }
  } ]
}

Hay un ejemplo completo disponible en el GitHub que se muestra cómo utilizar el API para trabajar con las notificaciones recibidas por una SQS cola de Amazon.