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

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

ایجاد مرجع

برای بارگذاری فایل، ابتدا یک مرجع Cloud Storage ایجاد کنید به مکانی در Cloud Storage که می‌خواهید فایل را در آن بارگذاری کنید.

می‌توانید با افزودن مسیرهای فرزند به ریشه Cloud Storage bucket، مرجع ایجاد کنید:

// 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 bucket بارگذاری کنید. مرجع شما باید به نشانی وب فرزند اشاره کند.

بارگذاری فایل‌ها

وقتی مرجع داشته باشید، می‌توانید فایل‌ها را به دو روش در 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);
}

مدیریت خطا

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

مراحل بعدی

اکنون که فایل‌ها را بارگذاری کرده‌اید، بیایید با نحوه بارگیری آن‌ها از Cloud Storage آشنا شویم.