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

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

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

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

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> برمی‌گرداند که وقتی «آینده» تکمیل می‌شود حاوی اطلاعاتی درباره فایل خواهد بود. می‌توانید از 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 آشنا شویم.