بارگیری فایل‌ها با 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);

At the point the request has been made but we have to wait for the Future to complete before we can read the file. ازآنجایی‌که بازی‌ها معمولاً در یک حلقه اجرا می‌شوند و کمتر از سایر برنامه‌ها مبتنی بر فراخوانی برگشتی هستند، معمولاً برای تکمیل نظرسنجی خواهید کرد.

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

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

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