تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تحميل ملفات باستخدام 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 بطريقتين:

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

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

تُعد الطريقة 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.