إدراج الملفات باستخدام Cloud Storage على Flutter

تتيح لك مساحة تخزين Cloud Storage لـ Firebase إدراج محتويات مجموعة بيانات Cloud Storage. تعرض حزم SDK كلاً من العناصر وبادئات الكائنات ضِمن مرجع Cloud Storage الحالي.

تتطلب المشاريع التي تستخدم List API الإصدار 2 من "قواعد الأمان" في مساحة تخزين سحابية لـ Firebase. إذا كان لديك مشروع حالي على Firebase، اتّبِع الخطوات الواردة في دليل "قواعد الأمان".

تستخدِم list() واجهة برمجة التطبيقات Google Cloud Storage List API. في مساحة تخزين سحابية لـ Firebase، نستخدم / كمحدِّد، ما يسمح لنا بمحاكاة دلالات نظام الملفات. للسماح بالتنقّل بكفاءة في مجموعات بيانات Cloud Storage الكبيرة والتسلسلية، تعرض List API البادئات والعناصر بشكل منفصل. على سبيل المثال، إذا حمّلت ملفًا واحدًا /images/uid/file1،

  • ستعرض الدالة root.child('images').listAll() السلسلة /images/uid كبادئة.
  • root.child('images/uid').listAll() ستعرض الملف كعنصر.

لا تعرض حزمة تطوير البرامج (SDK) الخاصة بمساحة تخزين Cloud Storage لـ Firebase مسارات الكائنات التي تحتوي على شرطتَين مائلتَين متتاليتَين/ (`//`) أو تنتهي بشرطة مائلة (/). على سبيل المثال، لنفترض أنّ لديك مجموعة بيانات تحتوي على الكائنات التالية:

  • correctPrefix/happyItem
  • wrongPrefix//sadItem
  • lonelyItem/

ستؤدي عمليات الإدراج على العناصر في مجموعة البيانات هذه إلى النتائج التالية:

  • تعرض عملية الإدراج في الجذر مراجع correctPrefix وwrongPrefix وlonelyItem كـ prefixes.
  • تعرض عملية الإدراج في الـ correctPrefix/ مراجع correctPrefix/happyItem كـ items.
  • لا تعرض عملية الإدراج في wrongPrefix/ أي مراجع لأنّ wrongPrefix//sadItem تحتوي على شرطتَين مائلتَين/ متتاليتَين.
  • لا تعرض عملية الإدراج في lonelyItem/ أي مراجع لأنّ الكائن lonelyItem/ ينتهي بـ /.

إدراج جميع الملفات

يمكنك استخدام listAll لجلب جميع نتائج دليل معيّن. يُنصح باستخدام هذه الطريقة مع الأدلة الصغيرة لأنّه يتم تخزين جميع النتائج مؤقتًا في الذاكرة. قد لا تعرض العملية أيضًا لقطة متّسقة إذا تمت إضافة كائنات أو إزالتها أثناء العملية.

بالنسبة إلى القوائم الكبيرة، استخدِم طريقة list() المقسَّمة إلى صفحات لأنّ listAll() تخزّن جميع النتائج مؤقتًا في الذاكرة.

يوضّح المثال التالي طريقة استخدام listAll.

final storageRef = FirebaseStorage.instance.ref().child("files/uid");
final listResult = await storageRef.listAll();
for (var prefix in listResult.prefixes) {
  // The prefixes under storageRef.
  // You can call listAll() recursively on them.
}
for (var item in listResult.items) {
  // The items under storageRef.
}

تقسيم نتائج الإدراج إلى صفحات

تفرض واجهة برمجة التطبيقات list() حدًا على عدد النتائج التي تعرضها. توفّر list() عرضًا ثابتًا لمشاهدة صفحة على الويب وتعرض pageToken الذي يسمح بالتحكّم في وقت جلب نتائج إضافية.

يشفّر pageToken المسار والإصدار الخاصَين بالعنصر الأخير الذي تم عرضه في النتيجة السابقة. في طلب لاحق باستخدام pageToken، يتم عرض العناصر التي تأتي بعد pageToken.

يوضّح المثال التالي طريقة تقسيم نتيجة إلى صفحات:

Stream<ListResult> listAllPaginated(Reference storageRef) async* {
  String? pageToken;
  do {
    final listResult = await storageRef.list(ListOptions(
      maxResults: 100,
      pageToken: pageToken,
    ));
    yield listResult;
    pageToken = listResult.nextPageToken;
  } while (pageToken != null);
}

التعامل مع الأخطاء

تفشل الدالتان list() وlistAll() إذا لم تتم ترقية "قواعد الأمان" إلى الإصدار 2. رقِّ قواعد الأمان إذا ظهر لك هذا الخطأ:

Listing objects in a bucket is disallowed for rules_version = "1".
Please update storage security rules to rules_version = "2" to use list.

قد تشير الأخطاء المحتمَلة الأخرى إلى أنّ المستخدم ليس لديه الإذن المناسب. يمكنك الاطّلاع على مزيد من المعلومات عن الأخطاء في صفحة التعامل مع الأخطاء.