تتيح لك خدمة 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 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!"); } });
التنزيل من خلال ساحة مشاركات
يتيح لك تنزيل الملف باستخدام ساحة مشاركات معالجة البيانات أثناء تحميلها.
ويمنحك ذلك مرونة قصوى عند التعامل مع عملية التنزيل. استدعِ GetStreamAsync() ومرِّر معالج ساحة المشاركات الخاص بك كمعلَمة أولى.
سيتم استدعاء هذا المفوّض على سلسلة محادثات في الخلفية باستخدام ساحة مشاركات تتيح لك إجراء عمليات أو حسابات مكثفة من حيث وقت الاستجابة، مثل تخزين المحتوى على القرص.
// 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 وتعديلها.