بارگیری فایل‌ها با Cloud Storage برای C++‎

Cloud Storage for Firebase به شما امکان می‌دهد به‌سرعت و به‌آسانی فایل‌ها را از یک سطل Cloud Storage که توسط Firebase ارائه و مدیریت می‌شود بارگیری کنید.

ایجاد مرجع

برای بارگیری فایل، ابتدا مرجع Cloud Storage ایجاد کنید تا فایل موردنظرتان بارگیری شود.

می‌توانید با افزودن مسیرهای فرزند به ریشه Cloud Storage bucket، مرجع ایجاد کنید یا می‌توانید از نشانی وب موجود 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. تولید کردن نشانی وب رشته‌ای که فایل را به‌صورت آنلاین نشان می‌دهد

بارگیری در حافظه

بااستفاده از روش 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);

در این نقطه، درخواست انجام شده است اما باید منتظر بمانیم تا Future تکمیل شود تا بتوانیم فایل را بخوانیم. ازآنجایی‌که بازی‌ها معمولاً در یک حلقه اجرا می‌شوند و نسبت‌به برنامه‌های دیگر کمتر مبتنی بر فراخوانی برگشتی هستند، معمولاً برای تکمیل نظرسنجی خواهید کرد.

// 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 می‌گیرد که می‌توانید از آن برای مدیریت بارگیری‌تان استفاده کنید. برای اطلاعات بیشتر، به مدیریت بارگیری‌ها مراجعه کنید.

تولید کردن نشانی وب بارگیری

If you already have download infrastructure based around URLs, or just want a URL to share, you can get the download URL for a file by calling the GetDownloadUrl() method on a Cloud Storage reference.

// 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 ذخیره شده‌اند، فراداده دریافت و به‌روز کنید.