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

تتيح لك أداة 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 بثلاث طرق:

  1. التنزيل إلى مخزن مؤقت في الذاكرة
  2. التنزيل إلى مسار محدّد على الجهاز
  3. إنشاء عنوان 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.