בעזרת 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.
אי אפשר להעלות נתונים עם הפניה לרמה הבסיסית (root) של הקטגוריה של 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
באמצעות ה-method putString()
. לדוגמה, כדי להעלות מחרוזת טקסט שמקודדת בתור כתובת URL של נתונים:
String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';
try {
await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
// ...
}
העלאת נתונים גולמיים
אפשר להעלות נתונים מוקלדים ברמה נמוכה יותר בצורת Uint8List
למקרים שבהם העלאת מחרוזת או File
לא מעשית. במקרה כזה, קוראים ל-method putData()
עם הנתונים:
try {
// Upload raw data.
await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
// ...
}
קבלת כתובת URL להורדה
אחרי שמעלים קובץ, אפשר לקבל כתובת URL להורדת הקובץ על ידי קריאה ל-method getDownloadUrl()
ב-Reference
:
await mountainsRef.getDownloadURL();
הוספת מטא-נתונים של קובץ
אפשר גם לכלול מטא-נתונים כשאתם מעלים קבצים.
המטא-נתונים האלו מכילים מאפיינים אופייניים של מטא-נתונים של קובץ, כמו contentType
(שנקרא בדרך כלל סוג MIME). ה-method 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.