العمل مع S3 والتخزين السحابي في Java: مكتبة AWS SDK

العمل مع S3 والتخزين السحابي في Java باستخدام AWS SDK

أصبحت مخازن الكائنات السحابية عبر بروتوكول S3 (Amazon Simple Storage Service) المعيار الفعلي لتخزين البيانات غير المهيكلة. في Java، للعمل مع المخازن المتوافقة مع S3 (Amazon S3، MinIO، Yandex Object Storage، DigitalOcean Spaces وغيرها) تُستخدم المكتبة الرسمية AWS SDK for Java. في هذه المقالة، سنشرح كيفية التوصيل، تهيئة العميل، والعمليات الأساسية على الملفات.

توصيل AWS SDK

للعمل مع S3، أضف التبعية في pom.xml (Maven):

<dependency>    <groupId>software.amazon.awssdk</groupId>    <artifactId>s3</artifactId>    <version>2.27.0</version></dependency>

لـ Gradle:

implementation 'software.amazon.awssdk:s3:2.27.0'

إنشاء عميل S3

يتم تكوين العميل عبر الباني (Builder). بالنسبة لـ Amazon S3، يكفي تحديد المنطقة:

S3Client s3 = S3Client.builder()    .region(Region.EU_CENTRAL_1)    .build();

للمخازن المتوافقة (MinIO، Yandex Object Storage)، يجب تحديد نقطة النهاية (endpoint) وبيانات الاعتماد (credentials):

String endpoint = "https://storage.yandexcloud.net";String accessKey = "YOUR_ACCESS_KEY";String secretKey = "YOUR_SECRET_KEY";

S3Client s3 = S3Client.builder()    .endpointOverride(URI.create(endpoint))    .region(Region.US_EAST_1) // يمكن أن تكون المنطقة أي شيء    .credentialsProvider(StaticCredentialsProvider.create(        AwsBasicCredentials.create(accessKey, secretKey)))    .build();

العمليات الأساسية على الحاويات (Buckets)

• إنشاء حاوية
• التحقق من الوجود
• حذف الحاوية

مثال على إنشاء حاوية:

String bucketName = "my-java-bucket";try {    s3.createBucket(CreateBucketRequest.builder()        .bucket(bucketName)        .build());    System.out.println("تم إنشاء الحاوية: " + bucketName);} catch (S3Exception e) {    System.err.println("خطأ: " + e.awsErrorDetails().errorMessage());}

رفع الملفات (Upload)

يمكن رفع ملف من تيار (stream)، نص (string)، أو ملف محلي:

// رفع من ملف محليs3.putObject(PutObjectRequest.builder()        .bucket(bucketName)        .key("docs/report.pdf")        .build(),    RequestBody.fromFile(Paths.get("/home/user/report.pdf")));

// رفع نص كملف نصيs3.putObject(PutObjectRequest.builder()        .bucket(bucketName)        .key("hello.txt")        .contentType("text/plain")        .build(),    RequestBody.fromString("Hello, S3!"));

تنزيل الملفات (Download)

لاسترجاع كائن، استخدم getObject:

// تنزيل إلى ملفs3.getObject(GetObjectRequest.builder()        .bucket(bucketName)        .key("docs/report.pdf")        .build(),    ResponseTransformer.toFile(Paths.get("downloaded_report.pdf")));

// تنزيل إلى نصString content = s3.getObjectAsBytes(GetObjectRequest.builder()        .bucket(bucketName)        .key("hello.txt")        .build())    .asUtf8String();System.out.println(content);

حذف الكائنات

s3.deleteObject(DeleteObjectRequest.builder()    .bucket(bucketName)    .key("hello.txt")    .build());System.out.println("تم حذف الملف");

قائمة الكائنات في الحاوية

للحصول على قائمة بجميع الملفات (مع ترقيم الصفحات):

ListObjectsV2Request listReq = ListObjectsV2Request.builder()    .bucket(bucketName)    .maxKeys(100)    .build();

ListObjectsV2Response listRes = s3.listObjectsV2(listReq);for (S3Object obj : listRes.contents()) {    System.out.println(" - "