העלאת קבצים באמצעות Cloud Storage ל-C++

הפקודה 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 בשתי דרכים:

  1. העלאה ממאגר נתונים זמני של בייטים בזיכרון
  2. העלאה מנתיב קובץ שמייצג קובץ במכשיר

העלאה מנתונים בזיכרון

השיטה 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"
Future future = rivers_ref.PutBytes(byte_buffer, kByteBufferSize);

בנקודה שבה הבקשה נוצרה, אבל אנחנו צריכים לחכות עד שה-Future יושלם לפני שהקובץ יועלה. משחקים בדרך כלל פועלים בלולאה, והם מבוססים פחות על קריאות חוזרות בהשוואה לאפליקציות אחרות, ולכן בדרך כלל מתבצעת בדיקה חוזרת כדי לראות אם הפעולה הושלמה.

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"
Future future = 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);
}

טיפול בשגיאות

יכולות להיות כמה סיבות לשגיאות בהעלאה, כולל קובץ מקומי שלא קיים או משתמש שאין לו הרשאה להעלות את הקובץ הרצוי. מידע נוסף על שגיאות זמין בקטע Handle Errors במסמכים.

השלבים הבאים

אחרי שהעליתם קבצים, נלמד איך להוריד אותם מ-Cloud Storage.