העלאת קבצים באמצעות 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.

אי אפשר להעלות נתונים עם הפניה לשורש של הקטגוריה של 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) {
  // ...
}

נהל העלאות

בנוסף להתחלת העלאות, אפשר להשהות, להמשיך ולבטל העלאות באמצעות השיטות 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.