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

Cloud Storage برای 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');

نظارت بر پیشرفت آپلود

برای مدیریت موفقیت، شکست، پیشرفت یا توقف در کار آپلود، می‌توانید به جریان رویداد یک کار گوش دهید:

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

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