تنزيل الملفات باستخدام Cloud Storage for Unity

يتيح لك 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 بأربع طرق:

  1. التنزيل من عنوان URL
  2. تنزيل البيانات إلى صفيف بايت
  3. تنزيل باستخدام بث
  4. تنزيلها إلى ملف على الجهاز

ستعتمد الطريقة التي ستستخدمها لاسترداد ملفاتك على الطريقة التي تريد بها استهلاك البيانات في لعبتك.

التنزيل من عنوان 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() واستخدام معالج البث الخاص بك كوسيطة أولى. سيتمّ استدعاء هذا المفوّض في سلسلة مهام في الخلفية باستخدام 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.