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