העלה קבצים עם 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 שלך. ההפניה שלך חייבת להפנות לכתובת צאצא.

העלה מקובץ

כדי להעלות קובץ, תחילה עליך לקבל את הנתיב המוחלט למיקום שלו במכשיר. לדוגמה, אם קיים קובץ בתוך ספריית המסמכים של היישום, השתמש בחבילה הרשמית 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 להורדת הקובץ על ידי קריאה לשיטת 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.