تحميل ملفات باستخدام 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. يجب أن يشير المرجع إلى عنوان URL فرعي.

تحميل ملفات

بعد الحصول على مرجع، يمكنك تحميل الملفات إلى Cloud Storage بطريقتَين:

  1. التحميل من مخزن مؤقت للوحدات البايتية في الذاكرة
  2. التحميل من مسار ملف يمثّل ملفًا على الجهاز

التحميل من البيانات في الذاكرة

الطريقة الأسهل لتحميل ملف إلى Cloud Storage هي استخدام طريقة PutData(). 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.