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

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 فراخوانی کنید.

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

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

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

آپلود از یک رشته

با استفاده از روش putString() می‌توانید داده‌ها را به‌عنوان رشته‌های رمزگذاری‌شده خام، base64 ، base64url یا data_url آپلود کنید. به عنوان مثال، برای آپلود یک رشته متنی رمزگذاری شده به عنوان URL داده:

String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';

try {
  await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
  // ...
}

آپلود داده های خام

برای مواردی که آپلود رشته یا File عملی نیست، می‌توانید داده‌های تایپ‌شده سطح پایین‌تر را در قالب Uint8List آپلود کنید. در این حالت، متد putData() را با داده های خود فراخوانی کنید:

try {
  // Upload raw data.
  await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

یک URL دانلود دریافت کنید

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

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

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

علاوه بر شروع آپلود، می توانید با استفاده از متدهای 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;
  }
});

رسیدگی به خطا

دلایل متعددی وجود دارد که ممکن است هنگام آپلود خطا رخ دهد، از جمله اینکه فایل محلی موجود نیست یا کاربر مجوز آپلود فایل مورد نظر را ندارد. اطلاعات بیشتر درباره خطاها را می توانید در بخش Handle Errors در اسناد بیابید.

مثال کامل

یک مثال کامل از آپلود با نظارت بر پیشرفت و مدیریت خطا در زیر نشان داده شده است:

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;
  }
});

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