Bekerja dengan Pemberitahuan Acara S3

Untuk membantu Anda memantau aktivitas di bucket, Amazon S3 dapat mengirim notifikasi saat peristiwa tertentu terjadi. Panduan Pengguna Amazon S3 memberikan informasi tentang notifikasi yang dapat dikirimkan bucket.

Anda dapat mengatur bucket untuk mengirim acara ke empat kemungkinan tujuan menggunakan SDK for Java:

• Topik Amazon Simple Notification Service

• Antrean Amazon Simple Queue Service

• AWS Lambda fungsi

• Amazon EventBridge

Saat menyiapkan bucket untuk mengirim acara EventBridge, Anda memiliki kemampuan untuk mengonfigurasi EventBridge aturan untuk meng-fanout acara yang sama ke beberapa tujuan. Saat Anda mengonfigurasi bucket untuk dikirim langsung ke salah satu dari tiga tujuan pertama, hanya satu jenis tujuan yang dapat ditentukan untuk setiap acara.

Di bagian selanjutnya, Anda akan melihat cara mengonfigurasi bucket menggunakan SDK for Java untuk mengirim Pemberitahuan Acara S3 dengan dua cara: langsung ke SQS antrian Amazon dan ke. EventBridge

Bagian terakhir menunjukkan kepada Anda cara menggunakan Pemberitahuan Acara S3 API untuk bekerja dengan notifikasi dengan cara yang berorientasi objek.

Konfigurasikan bucket untuk mengirim langsung ke tujuan

Contoh berikut mengonfigurasi bucket untuk mengirim notifikasi saat peristiwa pembuatan objek atau peristiwa penandaan objek terjadi terhadap 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)
    );
}

Kode yang ditunjukkan di atas mengatur satu antrian untuk menerima dua jenis acara. Dengan mudah, queueConfigurations metode ini memungkinkan Anda untuk mengatur beberapa tujuan antrian jika diperlukan. Selain itu, dalam notificationConfiguration metode ini Anda dapat mengatur tujuan tambahan, seperti satu atau beberapa SNS topik Amazon atau satu atau lebih fungsi Lambda. Cuplikan berikut menunjukkan contoh dengan dua antrian dan tiga jenis tujuan.

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

GitHub Repositori Contoh Kode berisi contoh lengkap untuk mengirim pemberitahuan acara S3 langsung ke antrian.

Konfigurasikan bucket untuk dikirim EventBridge

Contoh berikut mengonfigurasi bucket untuk mengirim notifikasi. 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());

Saat Anda mengonfigurasi bucket untuk mengirim acara EventBridge, Anda cukup menunjukkan EventBridge tujuan, bukan jenis acara atau tujuan akhir yang EventBridge akan dikirim. Anda mengkonfigurasi target akhir dan jenis acara dengan menggunakan EventBridge klien SDK Java.

Kode berikut menunjukkan cara mengkonfigurasi EventBridge untuk menyebarkan peristiwa yang dibuat objek ke topik dan antrian.

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

Untuk bekerja dengan EventBridge kode Java Anda, tambahkan ketergantungan pada eventbridge artefak ke file pom.xml Maven Anda.

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

GitHub Repositori Contoh Kode berisi contoh lengkap untuk mengirim pemberitahuan acara S3 ke EventBridge dan kemudian ke topik dan antrian.

Gunakan Pemberitahuan Acara S3 API untuk memproses acara

Setelah tujuan menerima acara notifikasi S3, Anda dapat memprosesnya dengan cara berorientasi objek dengan menggunakan Pemberitahuan Acara S3. API Anda dapat menggunakan Pemberitahuan Acara S3 API untuk bekerja dengan pemberitahuan acara yang dikirim langsung ke target (seperti yang ditunjukkan pada contoh pertama), tetapi tidak dengan notifikasi yang diarahkan. EventBridge Pemberitahuan acara S3 dikirim oleh bucket untuk EventBridge berisi struktur berbeda yang saat ini API tidak ditangani oleh Pemberitahuan Acara S3.

Tambahkan ketergantungan

Pemberitahuan Acara S3 API dirilis dengan versi 2.25.11 SDK untuk Java 2.x.

Untuk menggunakan Pemberitahuan Acara S3API, tambahkan elemen ketergantungan yang diperlukan ke Maven Anda pom.xml seperti yang ditunjukkan pada cuplikan berikut.

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

¹ Versi terbaru.

Gunakan S3EventNotification kelas

Buat S3EventNotification instance dari JSON string

Untuk mengubah JSON string menjadi S3EventNotification objek, gunakan metode statis S3EventNotification kelas seperti yang ditunjukkan pada contoh berikut.

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

Dalam contoh ini, fromJson metode mengubah JSON string menjadi S3EventNotification objek. Bidang yang hilang dalam JSON string akan menghasilkan null nilai di bidang objek Java yang sesuai dan bidang tambahan apa pun di dalamnya JSON akan diabaikan.

Lain APIs untuk catatan pemberitahuan acara dapat ditemukan dalam API referensi untukS3EventNotificationRecord.

Mengkonversi S3EventNotification instance ke JSON string

Gunakan metode toJson (ortoJsonPretty) untuk mengubah S3EventNotification objek menjadi JSON string seperti yang ditunjukkan pada contoh berikut.

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

Bidang untuk GlacierEventDataReplicationEventData,IntelligentTieringEventData,, dan LifecycleEventData dikecualikan dari JSON jika memang demikiannull. nullBidang lainnya akan diserialkan sebagainull.

Berikut ini menunjukkan contoh output dari toJsonPretty metode untuk peristiwa penandaan objek 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
      }
    }
  } ]
}

Contoh lengkap tersedia di GitHub yang menunjukkan cara menggunakan API untuk bekerja dengan notifikasi yang diterima oleh SQS antrian Amazon.