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

تتيح لك خدمة Cloud Storage for Firebase تنزيل المحتوى بسرعة وسهولة من Cloud Storage تم توفير الحزمة وإدارتها بواسطة Firebase.

ملاحظة: تتطلب حزمة Cloud Storage تلقائيًا مصادقة Firebase لتتمكّن من إجراء ما يلي: لتنفيذ أي إجراء على بيانات الحزمة أو ملفاتها. يمكنك تغيير قواعد أمان Firebase لخدمة Cloud Storage للسماح بالوصول غير المُصدَّق عليه. بما أنّ Firebase والقيمة التلقائية لمشروعك يشارك تطبيق App Engine هذه الحزمة، وقد يؤدي ضبط الوصول العلني إلى تحميل ملفات App Engine بشكل عام أيضًا. تأكد من تقييد الوصول إلى حزمة Cloud Storage مرة أخرى عند إعداد المصادقة.

إنشاء مرجع

لتنزيل ملف، عليك أولاً إنشاء مرجع 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.