بارگذاری فایل‌ها با Cloud Storage در Flutter

«فضای ذخیره‌سازی ابری ویژه Firebase» به شما امکان می‌دهد فایل‌ها را به‌سرعت و به‌آسانی در سطل فضای ذخیره‌سازی ابری بارگذاری کنید که توسط 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 bucket شما ارجاع می‌دهند بارگذاری کنید. مرجع شما باید به نشانی وب فرزند اشاره کند.

بارگذاری از فایل

برای بارگذاری فایل، ابتدا باید مسیر قطعی مکان آن در دستگاه را دریافت کنید. برای مثال، اگر فایلی در فهرست راهنمای اسناد برنامه وجود دارد، از بسته رسمی 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() بارگذاری کنید. برای مثال، برای بارگذاری رشته نوشتاری کدبندی‌شده به‌عنوان «نشانی وب داده»:

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) {
  // ...
}

دریافت نشانی وب بارگیری

پس‌از بارگذاری فایل، می‌توانید با فراخوانی روش getDownloadUrl() در Reference، نشانی وب بارگیری فایل را دریافت کنید:

await mountainsRef.getDownloadURL();

افزودن فراداده فایل

همچنین می‌توانید هنگام بارگذاری فایل‌ها، فراداده اضافه کنید. این فراداده شامل ویژگی‌های معمول فراداده فایل مثل contentType (که معمولاً به‌عنوان نوع MIME شناخته می‌شود) است. روش putFile() به‌طور خودکار نوع رسانه را از افزونه 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) {
  // ...
}

مدیریت بارگذاری‌ها

علاوه‌بر شروع بارگذاری‌ها، می‌توانید بااستفاده از روش‌های 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 آشنا شویم.