As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Trabalhe com notificações de eventos do S3

Para ajudar você a monitorar a atividade em seus buckets, o Amazon S3 pode enviar notificações quando determinados eventos acontecem. O Guia do usuário do Amazon S3 fornece informações sobre as notificações que um bucket pode enviar.

Você pode configurar um bucket para enviar eventos para quatro destinos possíveis usando o SDK for Java:

Ao configurar um bucket para o qual enviar eventos EventBridge, você pode configurar uma EventBridge regra para distribuir o mesmo evento para vários destinos. Quando você configura seu bucket para enviar diretamente para um dos três primeiros destinos, somente um tipo de destino pode ser especificado para cada evento.

Na próxima seção, você verá como configurar um bucket usando o SDK for Java para enviar notificações de eventos do S3 de duas maneiras: diretamente para uma SQS fila da Amazon e para. EventBridge

A última seção mostra como usar as notificações de eventos do S3 API para trabalhar com notificações de forma orientada a objetos.

Configurar um bucket para enviar diretamente para um destino

O exemplo a seguir configura um bucket para enviar notificações quando eventos de criação de objetos ou eventos de marcação de objetos ocorrem em um 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)
    );
}

O código mostrado acima configura uma fila para receber dois tipos de eventos. Convenientemente, o queueConfigurations método permite que você defina vários destinos de fila, se necessário. Além disso, no notificationConfiguration método, você pode definir destinos adicionais, como um ou mais SNS tópicos da Amazon ou uma ou mais funções Lambda. O trecho a seguir mostra um exemplo com duas filas e três 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)
        );

O GitHub repositório de exemplos de código contém o exemplo completo para enviar notificações de eventos do S3 diretamente para uma fila.

Configurar um bucket para enviar para EventBridge

O exemplo a seguir configura um bucket para o qual enviar EventBridge notificações.

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());

Ao configurar um bucket para o qual enviar eventos EventBridge, basta indicar o EventBridge destino, não os tipos de eventos nem o destino final para o qual o envio EventBridge será enviado. Você configura os alvos finais e os tipos de eventos usando o SDK EventBridge cliente Java.

O código a seguir mostra como configurar EventBridge para distribuir eventos criados por objetos para um tópico e uma fila.

   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 trabalhar com EventBridge seu código Java, adicione uma dependência do eventbridge artefato ao seu arquivo pom.xml Maven.

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

O GitHub repositório de exemplos de código contém o exemplo completo para enviar notificações de eventos do S3 para EventBridge e depois para um tópico e uma fila.

Use as notificações de eventos do S3 API para processar eventos

Depois que um destino recebe eventos de notificação do S3, você pode processá-los de forma orientada a objetos usando as notificações de eventos do S3. API Você pode usar as notificações de eventos do S3 API para trabalhar com notificações de eventos que são enviadas diretamente para um destino (conforme mostrado no primeiro exemplo), mas não com notificações roteadas. EventBridge As notificações de eventos do S3 enviadas por buckets EventBridge contêm uma estrutura diferente que as notificações de eventos do S3 API não manipulam atualmente.

Adicionar dependência

As notificações de eventos do S3 API foram lançadas com a versão 2.25.11 do SDK para Java 2.x.

Para usar as notificações de eventos do S3API, adicione o elemento de dependência necessário ao seu Maven, pom.xml conforme mostrado no trecho a seguir.

<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>

¹ Versão mais recente.

Use a S3EventNotification classe

Crie uma S3EventNotification instância a partir de uma JSON string

Para converter uma JSON string em um S3EventNotification objeto, use os métodos estáticos da S3EventNotification classe, conforme mostrado no exemplo a seguir.

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();                                                                                                   
    }
}

Neste exemplo, o fromJson método converte a JSON string em um S3EventNotification objeto. Os campos ausentes na JSON string resultarão em null valores nos campos do objeto Java correspondentes e quaisquer campos extras no JSON serão ignorados.

Outros APIs para um registro de notificação de eventos podem ser encontrados na API referência paraS3EventNotificationRecord.

Converter uma S3EventNotification instância em uma JSON string

Use o método toJson (outoJsonPretty) para converter um S3EventNotification objeto em uma JSON string, conforme mostrado no exemplo a seguir.

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);
    }
}

Os campos para GlacierEventDataReplicationEventData,IntelligentTieringEventData, e LifecycleEventData são excluídos do JSON se estiveremnull. Outros null campos serão serializados comonull.

Veja a seguir um exemplo de saída do toJsonPretty método para um evento de marcação de objetos do 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
      }
    }
  } ]
}

Um exemplo completo está disponível em GitHub que mostra como usar o API para trabalhar com notificações recebidas por uma SQS fila da Amazon.