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