العمل مع S3 في Node.js: مكتبة @aws-sdk/client-s3

مكتبة @aws-sdk/client-s3 للعمل مع S3 والتخزين السحابي في Node.js

أصبح التخزين السحابي جزءًا لا يتجزأ من تطبيقات الويب الحديثة. فهو يتيح تخزين ونقل الملفات بأي حجم، مع ضمان توفر عالٍ وقابلية للتوسع. في بيئة JavaScript (Node.js)، تُعد مكتبة @aws-sdk/client-s3 واحدة من أشهر المكتبات للعمل مع التخزين المتوافق مع S3، وهي AWS SDK الرسمي من الجيل الثالث.

توفر هذه المكتبة مجموعة كاملة من الأساليب للتفاعل مع Amazon S3، بالإضافة إلى أي تخزين كائني متوافق مع S3 (مثل MinIO، DigitalOcean Spaces، Yandex Object Storage، VK Cloud). في هذه المقالة، سنتناول التثبيت والإعداد والعمليات الأساسية: الرفع، التنزيل، الحذف، والحصول على قائمة الكائنات.

التثبيت والاستيراد

للبدء، قم بتثبيت الحزمة عبر npm:

npm install @aws-sdk/client-s3

بعد التثبيت، قم باستيراد الفئات اللازمة إلى مشروعك:

const { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command } = require('@aws-sdk/client-s3');

إعداد عميل S3

للاتصال بـ S3، يجب إنشاء مثيل للعميل مع تحديد المنطقة ومفاتيح الوصول، وعند الضرورة، نقطة النهاية (للتخزين الخارجي).

const s3Client = new S3Client({  region: 'ru-central1', // منطقة التخزين الخاصة بك  endpoint: 'https://storage.yandexcloud.net', // لـ Yandex Object Storage  credentials: {    accessKeyId: 'YOUR_ACCESS_KEY',    secretAccessKey: 'YOUR_SECRET_KEY'  }});

إذا كنت تستخدم Amazon S3 مباشرة، فلا حاجة لتحديد نقطة النهاية — سيقوم SDK بتحديدها تلقائيًا بناءً على المنطقة. للاختبار المحلي مع MinIO، حدد endpoint: 'http://localhost:9000' و forcePathStyle: true.

العمليات الأساسية مع S3

1. رفع ملف (PutObject)

لرفع ملف إلى الحاوية، استخدم الأمر PutObjectCommand. يمكن إرسال البيانات كنص، مخزن مؤقت، أو تيار.

const uploadFile = async (bucketName, key, body) => {  try {    const command = new PutObjectCommand({      Bucket: bucketName,      Key: key,      Body: body,      ContentType: 'text/plain' // اختياري    });    const response = await s3Client.send(command);    console.log('تم رفع الملف:', response);  } catch (err) {    console.error('خطأ في الرفع:', err);  }};

// مثال على الاستخدامuploadFile('my-bucket', 'hello.txt', 'مرحبًا بالعالم!');

2. تنزيل ملف (GetObject)

للحصول على كائن من التخزين، استخدم الأمر GetObjectCommand. يتم إرجاع البيانات كتيار يمكن تحويله إلى نص أو مخزن مؤقت.

const downloadFile = async (bucketName, key) => {  try {    const command = new GetObjectCommand({      Bucket: bucketName,      Key: key    });    const response = await s3Client.send(command);    const str = await response.Body.transformToString('utf-8');    console.log('محتوى الملف:', str);    return str;  } catch (err) {    console.error('خطأ في التنزيل:', err);  }};

// مثال على الاستخدامdownloadFile('my-bucket', 'hello.txt');

3. حذف ملف (DeleteObject)

يتم حذف الكائن باستخدام الأمر DeleteObjectCommand.

const deleteFile = async (bucketName, key) => {  try {    const command = new DeleteObjectCommand({      Bucket: bucketName,      Key: key    });    await s3Client.send(command);    console.log('تم حذف الملف');  } catch (err) {    console.error('خطأ في الحذف:', err);  }};

deleteFile('my-bucket', 'hello.txt');