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

// 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.