تحميل ملفات باستخدام Cloud Storage لـ C++

Cloud Storage for Firebase تتيح لك تحميل الملفات بسرعة وسهولة إلى مساحة تخزين سحابي في Cloud Storage توفّرها Firebase وتديرها.

إنشاء مرجع

لتحميل ملف، عليك أولاً إنشاء Cloud Storage مرجع إلى الموقع الجغرافي في 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 bucket. يجب أن يشير المرجع إلى عنوان URL فرعي.

تحميل ملفات

بعد الحصول على مرجع، يمكنك تحميل الملفات إلى 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.