Uso de notificaciones de eventos de S3 - AWS SDK for Java 2.x
Configuración de un bucket para enviarlo directamente a un destinoConfiguración de un bucket para enviarlo a EventBridgeUso de la API Notificaciones de eventos de S3 para procesar eventosOpciones de administración de notificaciones de eventos de S3

Uso de notificaciones de eventos de S3

Para ayudarle a monitorizar 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.

Puede configurar un bucket para enviar eventos a cuatro destinos posibles mediante el SDK para Java:

  • Temas de Amazon Simple Notification Service

  • Colas de Amazon Simple Queue Service

  • Funciones de AWS Lambda

  • Amazon EventBridge

Cuando configura un bucket para enviar eventos a EventBridge, puede configurar una regla de EventBridge para distribuir la distribución ramificada del 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á cómo configurar un bucket mediante el SDK para Java para enviar notificaciones de eventos de S3 de dos formas: directamente a una cola de Amazon SQS y a EventBridge.

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

Configuración de un bucket para enviarlo directamente a un destino

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

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 mostrado configura una cola para recibir dos tipos de eventos. Convenientemente, el método queueConfigurations permite configurar varios destinos de cola si es necesario. Además, en el método notificationConfiguration puede establecer destinos adicionales, como uno o más temas de Amazon SNS o una o más funciones de Lambda. El siguiente fragmento 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 repositorio de GitHub de ejemplos de código contiene el ejemplo completo para enviar notificaciones de eventos de S3 directamente a una cola.

Configuración de un bucket para enviarlo a EventBridge

En el siguiente ejemplo se configura un bucket para enviar notificaciones a EventBridge.

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 bucket para enviar eventos a EventBridge, basta con indicar el destino de EventBridge, no los tipos de eventos ni el destino final de envío de EventBridge. Los destinos definitivos y los tipos de eventos se configuran mediante el cliente de EventBridge del SDK de Java.

El código siguiente muestra cómo configurar EventBridge para realizar distribución ramificada de eventos de objeto creado 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 EventBridge en el código de Java, añada una dependencia en el artefacto eventbridge al archivo de pom.xml de Maven.

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

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

Uso de la API Notificaciones de eventos de S3 para procesar eventos

Una vez que un destino recibe eventos de notificación de S3, puede procesarlos de forma orientada a objetos mediante la API Notificaciones de eventos de S3. Puede utilizar la API Notificaciones de eventos de S3 para trabajar con notificaciones de eventos que se envían directamente a un destino (como se muestra en el primer ejemplo), pero no con notificaciones que se enrutan a través de EventBridge. Las notificaciones de eventos de S3 enviadas por buckets a EventBridge contienen una estructura diferente que la API Notificaciones de eventos de S3 no gestiona actualmente.

Adición de dependencia

La API Notificaciones de eventos de S3 se publicó con la versión 2.25.11 del SDK para Java 2.x.

Para usar la API Notificaciones de eventos de S3, agregue el elemento de dependencia necesario al pom.xml de Maven, 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.

Uso de la clase S3EventNotification

Creación de una instancia de S3EventNotification a partir de una cadena JSON

Para convertir una cadena JSON en un objeto S3EventNotification, use los métodos estáticos de la clase S3EventNotification, 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 método fromJson convierte la cadena JSON en un objeto S3EventNotification. La falta de campos en la cadena JSON generará valores de null en los campos de objetos de Java correspondientes y se ignorará cualquier campo adicional del JSON.

Encontrará otras API para un registro de notificaciones de eventos en la referencia de la API para S3EventNotificationRecord.

Conversión de una instancia de S3EventNotification en una cadena JSON

Utilice el método toJson (o toJsonPretty) para convertir un objeto S3EventNotification en una cadena JSON, 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 para GlacierEventData, ReplicationEventData, IntelligentTieringEventData y LifecycleEventData se excluyen del JSON si son null. Los demás campos null se serializarán como null.

A continuación, se muestra un ejemplo de resultado del método toJsonPretty 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" : "amzn-s3-demo-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 GitHub que muestra cómo usar la API para trabajar con las notificaciones recibidas por una cola de Amazon SQS.

Procese eventos de S3 en Lambda con bibliotecas de Java: AWS SDK for Java 2.x y aws-lambda-java-events

En lugar de usar el SDK para Java 2.x para procesar notificaciones de eventos de Amazon S3 en una función de Lambda, puede usar la biblioteca aws-lambda-java-events versión 3.x.x. AWS mantiene la biblioteca de aws-lambda-java-events de forma independiente y tiene sus propios requisitos de dependencia. La biblioteca de aws-lambda-java-events solo funciona con eventos de S3 en funciones de Lambda, mientras que el SDK para Java 2.x funciona con eventos de S3 en funciones de Lambda, Amazon SNS y Amazon SQS.

Ambos métodos modelan la carga útil de notificaciones de eventos de JSON de forma orientada a objetos con API similares. En la tabla siguiente se muestran las notables diferencias entre el uso de los dos métodos.

AWS SDK para Java aws-lambda-java-events library
Nomenclatura del paquete

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

 com.amazonaws.services.lambda.runtime.events.models.s3.S3EventNotification
RequestHandlerParámetro de

Escriba la implementación RequestHandler de la función de Lambda para recibir una cadena JSON:

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.eventnotifications.s3.model.S3EventNotification;

public class Handler implements RequestHandler<String, String> {

    @Override
        public String handleRequest(String jsonS3Event, Context context) {
            S3EventNotification s3Event = S3EventNotification
                                             .fromJson(jsonS3Event);
            // Work with the s3Event object.        
            ...
    }
}
 Escriba la implementación RequestHandler de la función de Lambda para recibir un objeto S3Event:
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.S3Event;

public class Handler implements RequestHandler<S3Event, String> {

    @Override
        public String handleRequest(S3Event s3event, Context context) {
            // Work with the s3Event object.        
            ...
    }
}
dependencias Maven 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.X.X</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3-event-notifications</artifactId>
    </dependency>
    <!-- Add other SDK dependencies that you need. -->
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.X.X</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <!-- The following two dependencies are for the 
         aws-lambda-java-events library. -->
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-lambda-java-core</artifactId>
        <version>1.2.3</version>     
    </dependency>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-lambda-java-events</artifactId>
        <version>3.15.0</version>
    </dependency>
    <!-- Add other SDK dependencies that you need. -->
</dependencies>