قم بتخزين الملفات وتقديمها باستخدام JavaScript SDK
يتدفق التخزين اليومي مع Client.storage: إدارة المجموعة، والتحميلات الفردية والمتعددة الأجزاء، والتنزيلات المتدفقة، وعناوين URL الموقعة HMAC، واستعادة المهملات.
إدارة دلو#
تقوم مجموعة بتجميع الملفات وتقرر ما إذا كانت عامة أم لا. يتطلب إنشاء المجموعات وحذفها مفتاح service_role. تتطلب مجموعات القائمة مستخدمًا مسجل الدخول أو مفتاح service_role (يستقبل المفتاح المجهول 403 FORBIDDEN).
// إنشاء مجموعة عامة (يمكن لأي شخص قراءة الكائنات بدون مفاتيح واجهة برمجة التطبيقات)
await admin.storage.createBucket('avatars', { public: true })
// إنشاء مجموعة خاصة (يمكن لمالكي الكائنات أو Service_role فقط قراءتها)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // حد 10 ميجابايت لكل ملف
allowedMimeTypes: ['application/pdf'],
})
// قائمة الدلاء التي يمكن الوصول إليها
const { data: buckets, error } = await admin.storage.listBuckets()
يقبل الدلو أيضًا fileSizeLimit (بالبايت) و allowedMimeTypes. يؤدي التحميل الكبير جدًا إلى 413 PAYLOAD_TOO_LARGE، بينما يعرض النوع غير المسموح به 400 BAD_REQUEST.
تحميل، تنزيل، قائمة، إزالة#
const bucket = aura.storage.from('invoices')
// التحميل: ملف، أو Blob، أو Buffer، أو Uint8Array
// يتم تقسيم الملفات التي يزيد حجمها عن 5 ميجابايت تلقائيًا إلى أجزاء متعددة الأجزاء
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → { المفتاح، المجموعة، عنوان url، الحجم، content_type، etag }
// استبدال ملف موجود يملكه المستخدم الحالي
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// قائمة الملفات تحت بادئة / مجلد
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// قم بتنزيل الملف باعتباره Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// دفق التنزيل دون تحميل الملف بأكمله في الذاكرة
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// إزالة ملف (يتم نقله إلى سلة المهملات افتراضيًا مع الاحتفاظ به لمدة 30 يومًا)
await bucket.remove([`${user.id}/2026-10.pdf`])
// الحذف الدائم (تجاوز سلة المهملات وتحرير حصة القرص على الفور)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
السلوكيات الرئيسية في وقت التشغيل:
- يؤدي تحميل مسار موجود إلى إرجاع
409 CONFLICTما لم يتم توفيرupsert: true. - يتم رفض التحميلات المجهولة مع
403 FORBIDDENفي كل من المجموعات الخاصة والعامة (تتطلب الكتابة JWT أو مفتاح خدمة مصادق عليه). - حماية اجتياز المسار: المسارات التي تحتوي على
..أو أحرف غير قانونية ترجع400 INVALID_PATHدون طرح استثناءات غير معالجة. - عزل المستخدم: لا يمكن لمستخدم واحد الكتابة فوق أو حذف الملفات المملوكة لمستخدم آخر (
owner_id = auth.uid()). قم ببناء المسارات باستخدام المجلدات المخصصة للمستخدم مثل${user.id}/....
مشاركة ملف (عناوين URL العامة والموقعة)#
// 1. المجموعة العامة: عنوان URL الدائم المباشر (يتم تقديمه بدون مفاتيح واجهة برمجة التطبيقات)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// فرض التنزيل كمرفق باسم ملف مخصص
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. المجموعة الخاصة: HMAC عنوان URL موقّع مع TTL قابل للتكوين
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
`${user.id}/2026-10.pdf`,
300, // صالحة لمدة 300 ثانية (5 دقائق)
{ download: true }
)
// يحتوي data.signedUrl وdata.url على عنوان URL الموقع HMAC
// 3. التحميل المباشر للمتصفح دون الكشف عن المفاتيح السرية
// من جانب الخادم (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// عميل المتصفح (لا يلزم وجود مفتاح API):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
تعمل عناوين URL الموقعة على إغلاق طريقة HTTP (GET أو PUT) والحاوية والمفتاح والطابع الزمني لانتهاء الصلاحية. بمجرد انتهاء الصلاحية أو في حالة حذف الكائن، تتلقى الطلبات 403 FORBIDDEN.
من يستطيع أن يفعل ماذا (مصفوفة الوصول)#
| العمل | مفتاح مجهول (anon) | مستخدم قام بتسجيل الدخول (authenticated) | دور الخدمة (service_role) |
|---|---|---|---|
| قراءة الملف في مجموعة عامة | نعم | نعم | نعم |
| قراءة الملف في مجموعة خاصة | لا (403) | المالك فقط (owner_id = auth.uid()) | نعم |
| تحميل ملف جديد | لا (403) | نعم (يصبح المالك) | نعم |
استبدل (upsert) أو احذف | لا (403) | المالك فقط | نعم |
| قائمة الملفات في مجموعة عامة | نعم | نعم | نعم |
| قائمة الملفات في مجموعة خاصة | لا (403) | المالك فقط (مرشح RLS) | نعم |
| إنشاء المجموعات أو تحديثها أو حذفها | لا (403) | لا (403) | نعم |
| عناوين URL للتحميل الموقعة | لا (403) | لا (403) | نعم |
يتم التعرف على المالك من خلال الموضوع JWT (auth.uid()). في كل من الحاويات العامة والخاصة، لا يمكن للمستخدمين الكتابة فوق كائنات المستخدمين الآخرين أو تدميرها.
نقل ونسخ والبيانات الوصفية والمهملات#
// نسخ ملف (يحتفظ بنوع المحتوى الأصلي وبيانات التعريف المخصصة)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// نقل أو إعادة تسمية ملف
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// فحص البيانات التعريفية للكائن (الحجم ونوع MIME وETag والبيانات التعريفية المخصصة)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// عناصر القائمة الموجودة حاليًا في سلة المهملات (الاحتفاظ لمدة 30 يومًا)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// استعادة كائن من سلة المهملات
await admin.storage.from('invoices').restore('2026/final.pdf')
لتحويلات الصور في الوقت الفعلي (تغيير الحجم، تحويل التنسيق، التدوير)، راجع مرجع SDK للتخزين.