تتيح لك خدمة Cloud Storage for Firebase تحميل الملفات بسرعة وسهولة إلى حزمة Cloud Storage التي توفّرها منصة Firebase وتديرها.
تحميل ملفات
لتحميل ملف إلى Cloud Storage، عليك أولاً إنشاء مرجع إلى المسار الكامل للملف، بما في ذلك اسم الملف.
// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();
// Create a reference to "mountains.jpg"
final mountainsRef = storageRef.child("mountains.jpg");
// Create a reference to 'images/mountains.jpg'
final mountainImagesRef = storageRef.child("images/mountains.jpg");
// While the file names are the same, the references point to different files
assert(mountainsRef.name == mountainImagesRef.name);
assert(mountainsRef.fullPath != mountainImagesRef.fullPath);
بعد إنشاء مرجع مناسب، يمكنك استدعاء طريقة
putFile()
أو putString()
أو putData()
لتحميل الملف
إلى Cloud Storage.
لا يمكنك تحميل بيانات تتضمّن إشارة إلى جذر حزمتك على Cloud Storage. يجب أن يشير المرجع إلى عنوان URL فرعي.
التحميل من ملف
لتحميل ملف، يجب أولاً الحصول على المسار المطلق لموقع الملف على الجهاز فقط. على سبيل المثال، إذا كان الملف موجودًا في دليل مستندات التطبيق،
استخدِم حزمة path_provider
الرسمية لإنشاء مسار ملف وتمريره إلى putFile()
:
Directory appDocDir = await getApplicationDocumentsDirectory();
String filePath = '${appDocDir.absolute}/file-to-upload.png';
File file = File(filePath);
try {
await mountainsRef.putFile(file);
} on firebase_core.FirebaseException catch (e) {
// ...
}
التحميل من سلسلة
ويمكنك تحميل البيانات كسلسلة أولية أو base64
أو base64url
أو data_url
مرمّزة باستخدام الطريقة putString()
. على سبيل المثال، لتحميل سلسلة نصية
مُرمَّزة كعنوان URL للبيانات:
String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';
try {
await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
// ...
}
تحميل البيانات الأولية
يمكنك تحميل بيانات مكتوبة بمستوى منخفض على شكل Uint8List
في الحالات التي يكون فيها تحميل سلسلة أو File
غير عملي. في هذه الحالة، يمكنك استدعاء طريقة putData()
مع بياناتك:
try {
// Upload raw data.
await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
// ...
}
الحصول على عنوان URL للتنزيل
بعد تحميل ملف، يمكنك الحصول على عنوان URL لتنزيل الملف من خلال طلب طريقة getDownloadUrl()
على Reference
:
await mountainsRef.getDownloadURL();
إضافة البيانات الوصفية للملف
يمكنك أيضًا تضمين البيانات الوصفية عند تحميل الملفات.
تحتوي هذه البيانات الوصفية على سمات نموذجية للبيانات الوصفية للملفات، مثل contentType
(يُشار إليها عادةً باسم نوع MIME). تستنتج الطريقة putFile()
تلقائيًا نوع MIME من الإضافة File
، ولكن يمكنك
إلغاء النوع الذي تم اكتشافه تلقائيًا من خلال تحديد contentType
في البيانات الوصفية. إذا لم توفّر contentType
وتعذّر على Cloud Storage استنتاج قيمة تلقائية من امتداد الملف، ستستخدم خدمة Cloud Storage application/octet-stream
. راجِع استخدام البيانات الوصفية للملفات.
try {
await mountainsRef.putFile(file, SettableMetadata(
contentType: "image/jpeg",
));
} on firebase_core.FirebaseException catch (e) {
// ...
}
إدارة التحميلات
بالإضافة إلى بدء عمليات التحميل، يمكنك إيقافها مؤقتًا واستئنافها وإلغاؤها باستخدام methods
pause()
وresume()
وcancel()
. يؤدي إيقاف الأحداث مؤقتًا واستئنافها إلى رفع
التغييرات في الحالة pause
وprogress
على التوالي. يؤدي إلغاء
عملية التحميل إلى تعذُّر تحميلها مع ظهور رسالة خطأ
تشير إلى أنّه تم إلغاؤها.
final task = mountainsRef.putFile(largeFile);
// Pause the upload.
bool paused = await task.pause();
print('paused, $paused');
// Resume the upload.
bool resumed = await task.resume();
print('resumed, $resumed');
// Cancel the upload.
bool canceled = await task.cancel();
print('canceled, $canceled');
تتبُّع مستوى تقدُّم عملية التحميل
يمكنك الاستماع إلى تدفق أحداث المهمة للتعامل مع النجاح أو الفشل أو التقدم أو الإيقاف المؤقت في مهمة التحميل:
نوع الحدث | الاستخدام المعتاد |
---|---|
TaskState.running |
يتم إطلاقها بشكل دوري أثناء نقل البيانات ويمكن استخدامها لتعبئة مؤشر التحميل/التنزيل. |
TaskState.paused |
يتم إطلاقها في أي وقت يتم فيه إيقاف المهمة مؤقتًا. |
TaskState.success |
يتم إصداره عند اكتمال المهمة بنجاح. |
TaskState.canceled |
يتم إطلاقها في أي وقت يتم فيه إلغاء المهمة. |
TaskState.error |
يتم إصدارها عند تعذّر التحميل. يمكن أن يحدث هذا بسبب انتهاء مهلة الشبكة أو تعذُّر التفويض أو إذا ألغيت المهمة. |
mountainsRef.putFile(file).snapshotEvents.listen((taskSnapshot) {
switch (taskSnapshot.state) {
case TaskState.running:
// ...
break;
case TaskState.paused:
// ...
break;
case TaskState.success:
// ...
break;
case TaskState.canceled:
// ...
break;
case TaskState.error:
// ...
break;
}
});
خطأ أثناء المعالجة
هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء أثناء التحميل، بما في ذلك عدم توفّر الملف على الجهاز أو عدم توفّر إذن لدى المستخدم لتحميل الملف المطلوب. يمكنك العثور على مزيد من المعلومات حول الأخطاء في قسم معالجة الأخطاء في المستندات.
مثال كامل
في ما يلي مثال كامل على عملية تحميل تتضمّن مراقبة مستوى التقدّم ومعالجة الأخطاء:
final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/path/to/mountains.jpg";
final file = File(filePath);
// Create the file metadata
final metadata = SettableMetadata(contentType: "image/jpeg");
// Create a reference to the Firebase Storage bucket
final storageRef = FirebaseStorage.instance.ref();
// Upload file and metadata to the path 'images/mountains.jpg'
final uploadTask = storageRef
.child("images/path/to/mountains.jpg")
.putFile(file, metadata);
// Listen for state changes, errors, and completion of the upload.
uploadTask.snapshotEvents.listen((TaskSnapshot taskSnapshot) {
switch (taskSnapshot.state) {
case TaskState.running:
final progress =
100.0 * (taskSnapshot.bytesTransferred / taskSnapshot.totalBytes);
print("Upload is $progress% complete.");
break;
case TaskState.paused:
print("Upload is paused.");
break;
case TaskState.canceled:
print("Upload was canceled");
break;
case TaskState.error:
// Handle unsuccessful uploads
break;
case TaskState.success:
// Handle successful uploads on complete
// ...
break;
}
});
الآن بعد أن حمّلت الملفات، لنتعرف على كيفية تنزيلها من Cloud Storage.