تتيح لك Cloud Storage for Firebase تنزيل الملفات بسرعة وسهولة من حزمة Cloud Storage التي توفّرها Firebase وتديرها.
إنشاء مرجع
لتنزيل ملف، عليك أولاً إنشاء Cloud Storage مرجع للملف الذي تريد تنزيله.
يمكنك إنشاء مرجع عن طريق إلحاق مسارات فرعية بجذر حزمة Cloud Storage، أو يمكنك إنشاء مرجع من عنوان URL حالي gs://
أو https://
يشير إلى عنصر في Cloud Storage.
// Create a reference with an initial file path and name StorageReference path_reference = storage->GetReference("images/stars.jpg"); // Create a reference from a Cloud Storage URI StorageReference gs_reference = storage->GetReferenceFromUrl("gs://bucket/images/stars.jpg"); // Create a reference from an HTTPS URL // Note that in the URL, characters are URL escaped! StorageReference https_reference = storage->GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");
تنزيل الملفات
بعد الحصول على مرجع، يمكنك تنزيل الملفات من Cloud Storage بثلاث طرق:
- التنزيل إلى مخزن مؤقت في الذاكرة
- التنزيل إلى مسار محدّد على الجهاز
- إنشاء عنوان URL لسلسلة تمثّل الملف على الإنترنت
التنزيل في الذاكرة
نزِّل الملف إلى مخزن مؤقت للبايت في الذاكرة باستخدام الطريقة GetBytes()
. هذه هي أسهل طريقة لتنزيل ملف بسرعة، ولكن يجب تحميل محتوى الملف بأكمله في الذاكرة. إذا طلبت ملفًا أكبر من الذاكرة المتاحة لتطبيقك، سيتعطّل تطبيقك. للحماية من مشاكل الذاكرة، احرص على ضبط الحد الأقصى للحجم على قيمة تعرف أنّ تطبيقك يمكنه التعامل معها، أو استخدِم طريقة تنزيل أخرى.
// Create a reference to the file you want to download StorageReference island_ref = storage_ref.Child("images/island.jpg"); // Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes) const size_t kMaxAllowedSize = 1 * 1024 * 1024 int8_t byte_buffer[kMaxAllowedSize]; firebase::Future<size_t> future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);
في هذه المرحلة، تم تقديم الطلب ولكن علينا الانتظار إلى أن يكتمل Future قبل أن نتمكّن من قراءة الملف. بما أنّ الألعاب تعمل عادةً في حلقة تكرار، وهي أقل اعتمادًا على عمليات معاودة الاتصال من التطبيقات الأخرى، عليك عادةً إجراء استطلاع للتأكّد من اكتمالها.
// In the game loop that polls for the result... if (future.status() != firebase::kFutureStatusPending) { if (future.status() != firebase::kFutureStatusComplete) { LogMessage("ERROR: GetBytes() returned an invalid future."); // Handle the error... } else if (future.Error() != firebase::storage::kErrorNone) { LogMessage("ERROR: GetBytes() returned error %d: %s", future.Error(), future.error_message()); // Handle the error... } else { // byte_buffer is now populated with data for "images/island.jpg" } }
تنزيل الملف إلى ملف محلي
تنزّل طريقة GetFile()
ملفًا مباشرةً على جهاز محلي. استخدِم هذا الخيار إذا أراد المستخدمون الوصول إلى الملف بلا إنترنت أو مشاركته في تطبيق آخر.
// Create a reference to the file you want to download StorageReference islandRef = storage_ref.Child("images/island.jpg"]; // Create local filesystem URL const char* local_url = "file:///local/images/island.jpg"; // Download to the local filesystem Future<size_t> future = islandRef.GetFile(local_url); // Wait for Future to complete... if (future.Error() != firebase::storage::kErrorNone) { // Uh-oh, an error occurred! } else { // The file has been downloaded to local file URL "images/island.jpg" }
يأخذ GetFile()
وسيطًا اختياريًا هو Controller
يمكنك استخدامه لإدارة عملية التنزيل. يمكنك الاطّلاع على مقالة إدارة عمليات التنزيل
للحصول على مزيد من المعلومات.
إنشاء عنوان URL للتنزيل
إذا كان لديك بنية أساسية للتنزيل تستند إلى عناوين URL، أو إذا كنت تريد الحصول على عنوان URL لمشاركته، يمكنك الحصول على عنوان URL للتنزيل لملف من خلال استدعاء الطريقة GetDownloadUrl()
على مرجع Cloud Storage.
// Create a reference to the file you want to download StorageReference stars_ref = storage_ref.Child("images/stars.jpg"); // Fetch the download URL firebase::Future<std::string> future = stars_ref.GetDownloadUrl(); // Wait for Future to complete... if (future.Error() != firebase::storage::kErrorNone) { // Uh-oh, an error occurred! } else { // Get the download URL for 'images/stars.jpg' std::string download_url = future.Result(); }
إدارة عمليات التنزيل
بالإضافة إلى بدء عمليات التنزيل، يمكنك إيقاف عمليات التنزيل مؤقتًا واستئنافها وإلغاؤها باستخدام الطرق Pause()
وResume()
وCancel()
على Controller
، والتي يمكنك تمريرها اختياريًا إلى الطريقتين GetBytes()
أو GetFile()
.
// Start downloading a file Controller controller; storage_ref.Child("images/mountains.jpg").GetFile(local_file, nullptr, &controller); // Pause the download controller.Pause(); // Resume the download controller.Resume(); // Cancel the download 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").GetFile(local_file, my_listener); }
معالجة الأخطاء
هناك عدة أسباب قد تؤدي إلى حدوث أخطاء أثناء التنزيل، بما في ذلك عدم توفّر الملف أو عدم حصول المستخدم على إذن بالوصول إلى الملف المطلوب. يمكنك الاطّلاع على مزيد من المعلومات حول الأخطاء في قسم التعامل مع الأخطاء في المستندات.
الخطوات التالية
يمكنك أيضًا الحصول على البيانات الوصفية وتعديلها للملفات المخزّنة في Cloud Storage.