تحميل الملفات باستخدام التخزين السحابي لـ C++

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

إنشاء مرجع

لتحميل ملف، قم أولاً بإنشاء مرجع 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

لا يمكنك تحميل البيانات بالإشارة إلى جذر مجموعة التخزين السحابي الخاصة بك. يجب أن يشير مرجعك إلى عنوان URL فرعي.

تحميل الملفات

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

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

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

تعد طريقة PutData() هي أبسط طريقة لتحميل ملف إلى Cloud Storage. يأخذ PutData() مخزنًا مؤقتًا للبايت ويعيد Future<Metadata> الذي سيحتوي على معلومات حول الملف عند اكتمال المستقبل. يمكنك استخدام 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.