تنزيل الملفات باستخدام Cloud Storage على Flutter

تتيح لك خدمة "التخزين في السحابة الإلكترونية" لبرنامج Firebase تنزيلملفاتك من مجموعة بيانات Cloud Storage بسرعة وسهولة، وهي مجموعة يوفّرها ويديرها Firebase.

إنشاء مرجع

لتنزيل ملف، عليك أولاً إنشاء مرجع في Cloud Storage للملف الذي تريد تنزيله.

يمكنك إنشاء مرجع من خلال إلحاق المسارات الفرعية بجذر حزمة Cloud Storage، أو يمكنك إنشاء مرجع من عنوان URL حالي gs:// أو https:// يشير إلى عنصر في Cloud Storage.

// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();

// Create a reference with an initial file path and name
final pathReference = storageRef.child("images/stars.jpg");

// Create a reference to a file from a Google Cloud Storage URI
final gsReference =
    FirebaseStorage.instance.refFromURL("gs://YOUR_BUCKET/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
final httpsReference = FirebaseStorage.instance.refFromURL(
    "https://firebasestorage.googleapis.com/b/YOUR_BUCKET/o/images%20stars.jpg");

تنزيل الملفات

بعد الحصول على مرجع، يمكنك تنزيل الملفات من Cloud Storage من خلال الاتصال بالاستدعاء getData() أو getStream(). إذا كنت تفضّل تنزيل الملف باستخدام مكتبة أخرى، يمكنك الحصول على عنوان URL للتنزيل باستخدام getDownloadUrl().

تنزيل المحتوى في الذاكرة

نزِّل الملف إلى UInt8List باستخدام الطريقة getData(). هذه هي أسهل طريقة لتنزيل ملف، ولكن يجب تحميل محتوى ملفك بالكامل في الذاكرة. إذا طلبت ملفًا أكبر من المساحة المتاحة في تطبيقك، سيتعطّل تطبيقك. للحماية من مشاكل الذاكرة، يستهلك تطبيق getData() الحد الأقصى من وحدات البايت لتنزيله. اضبط الحد الأقصى للحجم على قيمة يمكن لتطبيقك التعامل معها، أو استخدِم طريقة تنزيل أخرى.

final islandRef = storageRef.child("images/island.jpg");

try {
  const oneMegabyte = 1024 * 1024;
  final Uint8List? data = await islandRef.getData(oneMegabyte);
  // Data for "images/island.jpg" is returned, use this as needed.
} on FirebaseException catch (e) {
  // Handle any errors.
}

تنزيلها إلى ملف على الجهاز

تعمل طريقة writeToFile() على تنزيل ملف مباشرةً على جهاز محلي. استخدِم هذا الخيار إذا كان المستخدمون يريدون الوصول إلى الملف بلا اتصال بالإنترنت أو مشاركة الملف في تطبيق مختلف. يعرض writeToFile() DownloadTask يمكنك استخدامه لإدارة عملية التنزيل ومراقبة حالة التنزيل.

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

تنزيل البيانات من خلال عنوان URL

إذا كانت لديك بالفعل بنية أساسية للتنزيل تستند إلى عناوين URL، أو إذا كنت تريد فقط عنوان URL لمشاركته، يمكنك الحصول على عنوان URL للتنزيل لملف من خلال استدعاء الأسلوب getDownloadURL() في مرجع Cloud Storage.

final imageUrl =
    await storageRef.child("users/me/profile.png").getDownloadURL();

معالجة الأخطاء

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

مثال كامل

في ما يلي مثال كامل لتنزيل يتضمّن معالجة الأخطاء:

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

يمكنك أيضًا الحصول على البيانات الوصفية وتعديلها للملفات المخزّنة في Cloud Storage.