Cloud Storage for Firebase מאפשרת להעלות קבצים במהירות ובקלות לקטגוריה Cloud Storage ש-Firebase מספקת ומנהלת.
יצירת קובץ עזר
כדי להעלות קובץ, קודם צריך ליצור הפניה ל-Cloud Storage למיקום ב-Cloud Storage שאליו רוצים להעלות את הקובץ.
אפשר ליצור קובץ עזר על ידי צירוף נתיבים של צאצאים לשורש של הקטגוריה Cloud Storage:
// Create a root reference StorageReference storage_ref = storage->GetReference(); // Create a reference to "mountains.jpg" StorageReference mountains_ref = storage_ref.Child("mountains.jpg"); // Create a reference to 'images/mountains.jpg' StorageReference mountain_images_ref = storage_ref.Child("images/mountains.jpg"); // While the file names are the same, the references point to different files mountains_ref.name() == mountain_images_ref.name(); // true mountains_ref.full_path() == mountain_images_ref.full_path(); // false
אי אפשר להעלות נתונים עם הפניה לשורש של הקטגוריה Cloud Storage. ההפניה צריכה להפנות לכתובת URL של צאצא.
העלאת קבצים
אחרי שיוצרים קובץ עזר, אפשר להעלות קבצים ל-Cloud Storage בשתי דרכים:
- העלאה ממאגר בייטים בזיכרון
- העלאה מנתיב קובץ שמייצג קובץ במכשיר
העלאה מנתונים שבזיכרון
השיטה PutData()
היא הדרך הפשוטה ביותר להעלות קובץ אל Cloud Storage. הפונקציה PutData()
מקבלת מאגר בייטים ומחזירה Future<Metadata>
שיכיל מידע על הקובץ כשה-Future יושלם. אפשר להשתמש ב-Controller
כדי לנהל את ההעלאה ולעקוב אחרי הסטטוס שלה.
// Data in memory const size_t kByteBufferSize = ... uint8_t byte_buffer[kByteBufferSize] = { ... }; // Create a reference to the file you want to upload StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg"); // Upload the file to the path "images/rivers.jpg" Futurefuture = rivers_ref.PutBytes(byte_buffer, kByteBufferSize);
בשלב הזה הבקשה נשלחה, אבל אנחנו צריכים להמתין עד שהפעולה ב-Future תושלם כדי שהקובץ יועלה. משחקים בדרך כלל פועלים ברצף, והם פחות מונעים קריאה חוזרת (callback) בהשוואה לאפליקציות אחרות, לכן בדרך כלל תשאלו אותם כדי לסיים את הפעולה.
if (future.status() != firebase::kFutureStatusPending) { if (future.status() != firebase::kFutureStatusComplete) { LogMessage("ERROR: GetData() returned an invalid future."); // Handle the error... } else if (future.Error() != firebase::storage::kErrorNone) { LogMessage("ERROR: GetData() returned error %d: %s", future.Error(), future.error_message()); // Handle the error... } } else { // Metadata contains file metadata such as size, content-type, and download URL. Metadata* metadata = future.Result(); std::string download_url = metadata->download_url(); } }
העלאה מקובץ מקומי
אפשר להעלות קבצים מקומיים במכשירים, כמו תמונות וסרטונים מהמצלמה, באמצעות PutFile()
. הפונקציה PutFile()
מקבלת std::string
שמייצג את הנתיב לקובץ ומחזירה Future<Metadata>
שיכיל מידע על הקובץ כשה-Future יושלם. אפשר להשתמש ב-Controller
כדי לנהל את ההעלאה ולעקוב אחר הסטטוס שלה.
// File located on disk std::string local_file = ... // Create a reference to the file you want to upload StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg"); // Upload the file to the path "images/rivers.jpg" Futurefuture = rivers_ref.PutFile(localFile); // Wait for Future to complete... if (future.Error() != firebase::storage::kErrorNone) { // Uh-oh, an error occurred! } else { // Metadata contains file metadata such as size, content-type, and download URL. Metadata* metadata = future.Result(); std::string download_url = metadata->download_url(); }
אם רוצים לנהל באופן פעיל את ההעלאה, אפשר לספק Controller
לשיטות PutFile()
או PutBytes()
. כך תוכלו להשתמש ב-Controller כדי לעקוב אחרי פעולת ההעלאה המתמשכת. למידע נוסף, ראו ניהול העלאות.
הוספת מטא-נתונים של קובץ
אפשר גם לכלול מטא-נתונים כשמעלים קבצים. המטא-נתונים האלה מכילים מאפיינים אופייניים של מטא-נתונים של קבצים, כמו name
, size
ו-content_type
(שנקראים בדרך כלל סוג MIME). השיטה PutFile()
מסיקה באופן אוטומטי את סוג התוכן מהסיומת של שם הקובץ, אבל אפשר לשנות את הסוג שזוהה באופן אוטומטי על ידי ציון content_type
במטא-נתונים. אם לא מספקים content_type
, ו-Cloud Storage לא יכול להסיק מהי ברירת המחדל מסיומת הקובץ, Cloud Storage ישתמש ב-application/octet-stream
. מידע נוסף על מטא-נתונים של קבצים מופיע בקטע שימוש במטא-נתונים של קבצים.
// Create storage reference StorageReference mountains_ref = storage_ref.Child("images/mountains.jpg"); // Create file metadata including the content type StorageMetadata metadata; metadata.set_content_type("image/jpeg"); // Upload data and metadata mountains_ref.PutBytes(data, metadata); // Upload file and metadata mountains_ref.PutFile(local_file, metadata);
נהל העלאות
בנוסף להפעלת העלאות, אפשר להשהות, להמשיך ולבטל העלאות באמצעות השיטות Pause()
, Resume()
ו-Cancel()
ב-Controller
, שאפשר להעביר לשיטות PutBytes()
או PutFile()
.
// Start uploading a file firebase::storage::Controller controller; storage_ref.Child("images/mountains.jpg").PutFile(local_file, nullptr, &controller); // Pause the upload controller.Pause(); // Resume the upload controller.Resume(); // Cancel the upload controller.Cancel();
מעקב אחר התקדמות ההעלאה
אפשר לצרף מאזינים להעלאות כדי לעקוב אחרי התקדמות ההעלאה.
class MyListener : public firebase::storage::Listener { public: virtual void OnProgress(firebase::storage::Controller* controller) { // A progress event occurred } }; { // Start uploading a file MyEventListener my_listener; storage_ref.Child("images/mountains.jpg").PutFile(local_file, my_listener); }
טיפול בשגיאות
יש כמה סיבות לכך שעשויות להתרחש שגיאות בהעלאה, כולל הקובץ המקומי לא קיים או שהמשתמש לא קיבל הרשאה להעלות את הקובץ הרצוי. מידע נוסף על שגיאות זמין בקטע טיפול בשגיאות במסמכי העזרה.
השלבים הבאים
עכשיו, אחרי שהעליתם קבצים, נסביר איך להוריד אותם מ-Cloud Storage.