توضّح هذه الصفحة كيفية استخدام حزمة تطوير البرامج (SDK) لـ Cloud Storage for Firebase لتنزيل الملفات من حزمة Cloud Storage.
إنشاء مرجع
لتنزيل ملف، عليك أولاً إنشاء مرجع Cloud Storage للملف الذي تريد تنزيله.
يمكنك إنشاء مرجع من خلال إلحاق مسارات فرعية بجذر حزمة Cloud Storage، أو يمكنك إنشاء مرجع من عنوان URL حالي لـ gs:// أو https:// يشير إلى عنصر في Cloud Storage.
// Create a reference with an initial file path and name StorageReference pathReference = storage.GetReference("images/stars.jpg"); // Create a reference from a Google Cloud Storage URI StorageReference gsReference = storage.GetReferenceFromUrl("gs://bucket/images/stars.jpg"); // Create a reference from an HTTPS URL // Note that in the URL, characters are URL escaped! StorageReference httpsReference = storage.GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");
تنزيل الملفات
بعد الحصول على مرجع، يمكنك تنزيل الملفات من Cloud Storage بأربع طرق:
- التنزيل من عنوان URL
- التنزيل إلى مصفوفة بايت
- التنزيل من خلال البث
- التنزيل إلى ملف على الجهاز
تعتمد الطريقة التي ستستخدمها لاسترداد ملفاتك على الطريقة التي تريد بها استخدام البيانات في لعبتك.
التنزيل من عنوان URL
إذا أردت استخدام عنوان URL مع WWW أو UnityWebRequest في Unity، يمكنك الحصول على عنوان URL لتنزيل ملف من خلال استدعاء GetDownloadUrlAsync().
// Fetch the download URL reference.GetDownloadUrlAsync().ContinueWithOnMainThread(task => { if (!task.IsFaulted && !task.IsCanceled) { Debug.Log("Download URL: " + task.Result); // ... now download the file via WWW or UnityWebRequest. } });
التنزيل إلى مصفوفة بايت
يمكنك تنزيل الملف إلى مخزن بايت مؤقت في الذاكرة باستخدام طريقة GetBytesAsync(). تقوم هذه الطريقة بتحميل محتويات الملف بالكامل
في الذاكرة. إذا طلبت ملفًا أكبر من الذاكرة المتاحة لتطبيقك، سيتعطّل التطبيق. للحماية من مشاكل الذاكرة، تأكَّد من ضبط الحد الأقصى للحجم
على قيمة يمكن لتطبيقك التعامل معها، أو استخدِم طريقة تنزيل أخرى.
// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes) const long maxAllowedSize = 1 * 1024 * 1024; reference.GetBytesAsync(maxAllowedSize).ContinueWithOnMainThread(task => { if (task.IsFaulted || task.IsCanceled) { Debug.LogException(task.Exception); // Uh-oh, an error occurred! } else { byte[] fileContents = task.Result; Debug.Log("Finished downloading!"); } });
التنزيل من خلال بث
يتيح لك تنزيل الملف باستخدام Stream معالجة البيانات أثناء تحميلها.
يمنحك هذا أقصى قدر من المرونة عند التعامل مع عملية التنزيل. استدعِ الدالة GetStreamAsync ومرِّر معالج البث الخاص بك كوسيطة أولى. سيتم استدعاء هذا المفوَّض في سلسلة محادثات في الخلفية باستخدام Stream يتيح لك إجراء عمليات أو حسابات تتطلّب وقت استجابة مكثّفًا، مثل تخزين المحتوى على القرص.
// Download via a Stream reference.GetStreamAsync(stream => { // Do something with the stream here. // // This code runs on a background thread which reduces the impact // to your framerate. // // If you want to do something on the main thread, you can do that in the // progress eventhandler (second argument) or ContinueWith to execute it // at task completion. }, null, CancellationToken.None);
تتلقّى الدالة GetStreamAsync() وسيطة اختيارية بعد معالج البث تتيح لك إلغاء العملية أو تلقّي إشعار بشأن مستوى التقدّم.
التنزيل إلى ملف على الجهاز
تنزّل طريقة GetFileAsync() ملفًا مباشرةً على جهاز محلي. يمكنك استخدام هذا الخيار إذا أراد المستخدمون الوصول إلى الملف بلا إنترنت أو مشاركة الملف في تطبيق مختلف.
// Create local filesystem URL string localUrl = "file:///local/images/island.jpg"; // Download to the local filesystem reference.GetFileAsync(localUrl).ContinueWithOnMainThread(task => { if (!task.IsFaulted && !task.IsCanceled) { Debug.Log("File downloaded."); } });
يمكنك إرفاق مستمعين بعمليات التنزيل لمراقبة مستوى تقدّم عملية التنزيل. يتبع المستمع واجهة System.IProgress<T>
القياسية. يمكنك استخدام مثيل من فئة StorageProgress لتوفير
Action<T> الخاص بك كعملية استدعاء لعلامات التقدم.
// Create local filesystem URL string localUrl = "file:///local/images/island.jpg"; // Start downloading a file Task task = reference.GetFileAsync(localFile, new StorageProgress<DownloadState>(state => { // called periodically during the download Debug.Log(String.Format( "Progress: {0} of {1} bytes transferred.", state.BytesTransferred, state.TotalByteCount )); }), CancellationToken.None); task.ContinueWithOnMainThread(resultTask => { if (!resultTask.IsFaulted && !resultTask.IsCanceled) { Debug.Log("Download finished."); } });
معالجة الأخطاء
هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء أثناء التنزيل، بما في ذلك عدم وجود الملف، أو عدم حصول المستخدم على إذن للوصول إلى الملف المقصود. لمزيد من المعلومات حول الأخطاء، يُرجى الاطّلاع على معالجة الأخطاء.
الخطوات التالية
يمكنك أيضًا الحصول على البيانات الوصفية وتعديلها للملفات المخزّنة في Cloud Storage.