تنزيل الملفات باستخدام 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 وتعديلها.