انتقل إلى المحتوى
شعار أوراباسي
aurabase

قم بتخزين الملفات وتقديمها باستخدام JavaScript SDK

يتدفق التخزين اليومي مع Client.storage: إدارة المجموعة، والتحميلات الفردية والمتعددة الأجزاء، والتنزيلات المتدفقة، وعناوين URL الموقعة HMAC، واستعادة المهملات.

دليل عملي8 د قراءةالمستوى وسيطةتمت المراجعة في 28‏/10‏/2026

تمت ترجمة هذه الصفحة تلقائيًا. النسخة الإنجليزية موثوقة.

إدارة دلو#

تقوم مجموعة بتجميع الملفات وتقرر ما إذا كانت عامة أم لا. يتطلب إنشاء المجموعات وحذفها مفتاح service_role. تتطلب مجموعات القائمة مستخدمًا مسجل الدخول أو مفتاح service_role (يستقبل المفتاح المجهول 403 FORBIDDEN).

server/buckets.tstypescript
// إنشاء مجموعة عامة (يمكن لأي شخص قراءة الكائنات بدون مفاتيح واجهة برمجة التطبيقات)
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.

تحميل، تنزيل، قائمة، إزالة#

files.tstypescript
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 العامة والموقعة)#

share.tstypescript
// 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()). في كل من الحاويات العامة والخاصة، لا يمكن للمستخدمين الكتابة فوق كائنات المستخدمين الآخرين أو تدميرها.

نقل ونسخ والبيانات الوصفية والمهملات#

server/organise.tstypescript
// نسخ ملف (يحتفظ بنوع المحتوى الأصلي وبيانات التعريف المخصصة)
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 للتخزين.