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

Cloud Storage for Firebase מאפשר לך להוריד במהירות ובקלות קבצים מ-Cloud Storage קטגוריה שסופקה ומנוהלת על ידי Firebase.

יצירת קובץ עזר

כדי להוריד קובץ, קודם יצירת קובץ עזר של Cloud Storage לקובץ שרוצים להוריד.

אפשר ליצור קובץ עזר על ידי צירוף נתיבי צאצא לשורש של מקטגוריה אחת (Cloud Storage), או שאפשר ליצור קובץ עזר מקטגוריה קיימת כתובת URL מסוג gs:// או https:// שמפנה לאובייקט ב-Cloud Storage.

// Create a reference with an initial file path and name
StorageReference path_reference = storage->GetReference("images/stars.jpg");

// Create a reference from a Cloud Storage URI
StorageReference gs_reference = storage->GetReferenceFromUrl("gs://bucket/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference https_reference = storage->GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");

הורדת קבצים

כשיהיה לך קובץ עזר, תהיה לך אפשרות להוריד קבצים מ-Cloud Storage בשלוש דרכים:

  1. הורדה למאגר נתונים זמני בזיכרון
  2. הורדה לנתיב ספציפי במכשיר
  3. יצירת כתובת URL של מחרוזת שמייצגת את הקובץ אונליין

הורדה בזיכרון

מורידים את הקובץ למאגר אחסון של בייטים בזיכרון באמצעות השיטה GetBytes(). זו הדרך הקלה ביותר להוריד קובץ במהירות, אבל צריך לטעון את כל תוכן הקובץ לזיכרון. אם מבקשים קובץ גדול יותר מהזיכרון הזמין באפליקציה, היא תקרוס. כדי להגן מפני בעיות זיכרון, צריך ליצור להגדיר את הגודל המקסימלי לערך שאתם יודעים שהאפליקציה יכולה לטפל בו או להשתמש בו שיטת הורדה אחרת.

// Create a reference to the file you want to download
StorageReference island_ref = storage_ref.Child("images/island.jpg");

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const size_t kMaxAllowedSize = 1 * 1024 * 1024
int8_t byte_buffer[kMaxAllowedSize];
firebase::Future<size_t> future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);

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

// In the game loop that polls for the result...

if (future.status() != firebase::kFutureStatusPending) {
  if (future.status() != firebase::kFutureStatusComplete) {
    LogMessage("ERROR: GetBytes() returned an invalid future.");
    // Handle the error...
  } else if (future.Error() != firebase::storage::kErrorNone) {
    LogMessage("ERROR: GetBytes() returned error %d: %s", future.Error(),
               future.error_message());
    // Handle the error...
  } else {
    // byte_buffer is now populated with data for "images/island.jpg"
  }
}

הורדה לקובץ מקומי

השיטה GetFile() מורידה קובץ ישירות למכשיר מקומי. כדאי להשתמש באפשרות הזו אם המשתמשים רוצים שתהיה להם גישה לקובץ כשהם במצב אופליין או כדי לשתף אפליקציה אחרת.

// Create a reference to the file you want to download
StorageReference islandRef = storage_ref.Child("images/island.jpg"];

// Create local filesystem URL
const char* local_url = "file:///local/images/island.jpg";

// Download to the local filesystem
Future<size_t> future = islandRef.GetFile(local_url);

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // The file has been downloaded to local file URL "images/island.jpg"
}

GetFile() לוקח ארגומנט Controller אופציונלי שבהם אפשר להשתמש כדי לנהל את ההורדות. מידע נוסף זמין בקטע ניהול ההורדות אפשר לקבל מידע נוסף.

יצירת כתובת URL להורדה

אם כבר יש לכם תשתית הורדות המבוססת על כתובות URL, או אם אתם רק רוצים לכתובת אתר לשיתוף, תוכל לקבל את כתובת האתר להורדה של קובץ באמצעות קריאה GetDownloadUrl() בהפניה של Cloud Storage.

// Create a reference to the file you want to download
StorageReference stars_ref = storage_ref.Child("images/stars.jpg");

// Fetch the download URL
firebase::Future<std::string> future = stars_ref.GetDownloadUrl();

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // Get the download URL for 'images/stars.jpg'
  std::string download_url = future.Result();
}

ניהול ההורדות

בנוסף להפעלת הורדות, אפשר להשהות, להמשיך ולבטל הורדות באמצעות השיטות Pause(),‏ Resume() ו-Cancel() ב-Controller, שאפשר להעביר לשיטות GetBytes() או GetFile().

// Start downloading a file
Controller controller;
storage_ref.Child("images/mountains.jpg").GetFile(local_file, nullptr, &controller);

// Pause the download
controller.Pause();

// Resume the download
controller.Resume();

// Cancel the download
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").GetFile(local_file, my_listener);
}

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

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

השלבים הבאים

אפשר גם לקבל ולעדכן מטא-נתונים לקבצים שמאוחסנים ב-Cloud Storage.