فایل ها را با Cloud Storage در Flutter آپلود کنید

فضای ذخیره‌سازی ابری برای فایربیس به شما امکان می‌دهد تا به سرعت و به راحتی فایل‌ها را در یک مخزن ذخیره‌سازی ابری که توسط فایربیس ارائه و مدیریت می‌شود، آپلود کنید.

آپلود فایل‌ها

برای آپلود فایل در فضای ذخیره‌سازی ابری، ابتدا باید یک ارجاع به مسیر کامل فایل، شامل نام فایل، ایجاد کنید.

// 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() را برای آپلود فایل در فضای ذخیره‌سازی ابری فراخوانی کنید.

شما نمی‌توانید داده‌ها را با ارجاع به ریشه‌ی مخزن ذخیره‌سازی ابری خود آپلود کنید. ارجاع شما باید به یک URL فرزند اشاره کند.

آپلود از یک فایل

برای آپلود یک فایل، ابتدا باید مسیر مطلق آن را روی دستگاه دریافت کنید. برای مثال، اگر فایلی در دایرکتوری documents برنامه وجود دارد، از بسته رسمی 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() آپلود کنید. برای مثال، برای آپلود یک رشته متنی کدگذاری شده به عنوان Data 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) {
  // ...
}

دریافت آدرس اینترنتی دانلود

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

await mountainsRef.getDownloadURL();

افزودن متادیتای فایل

همچنین می‌توانید هنگام آپلود فایل‌ها، فراداده (metadata) را نیز اضافه کنید. این فراداده شامل ویژگی‌های معمول فراداده فایل مانند 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) {
  // ...
}

مدیریت آپلودها

علاوه بر شروع آپلود، می‌توانید با استفاده از متدهای pause() ، resume() و cancel() آپلودها را متوقف، از سر بگیرید و لغو کنید. رویدادهای Pause و resume به ترتیب باعث ایجاد تغییرات در وضعیت 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;
  }
});

حالا که فایل‌ها را آپلود کرده‌اید، بیایید یاد بگیریم که چگونه آنها را از فضای ذخیره‌سازی ابری دانلود کنیم .