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

يتيح لك Cloud Storage for Firebase تنزيل الملفات بسرعة وسهولة من حزمة Cloud Storage توفّرها وتديرها Firebase.

ملاحظة: تتطلّب حزمة Cloud Storage for Firebase تلقائيًا من Firebase Authentication تنفيذ أي إجراء على بيانات الحزمة أو ملفاتها. يمكنك تغيير Firebase Security Rules إلى Cloud Storage لالسماح بالوصول غير المعتمَد في حالات معيّنة. ومع ذلك، في معظم الحالات، ننصحك بشدة بحظر الوصول وإعداد قواعد أمان صارمة (خاصةً للتطبيقات العلنية). يُرجى العِلم أنّه في حال استخدام Google App Engine وامتلاك حزمة Cloud Storage تلقائية بتنسيق اسم *.appspot.com، قد تحتاج إلى مراعاة كيفية تأثير قواعد الأمان في الوصول إلى ملفات App Engine.

إنشاء مرجع

لتنزيل ملف، عليك أولاً إنشاء 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 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 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 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.