يسمح لك 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" Futurefuture = 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()
. تم قطع std::string
عن طريق PutFile()
.
تمثل المسار إلى الملف وترجع
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" Futurefuture = 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