بارگیری فایل‌ها با Cloud Storage برای Unity

‫Cloud Storage for Firebase به شما امکان می‌دهد فایل‌ها را به‌سرعت و به‌آسانی از باکت Cloud Storage ارائه‌شده و مدیریت‌شده توسط Firebase بارگیری کنید.

ایجاد مرجع

برای بارگیری فایل، ابتدا مرجع Cloud Storage ایجاد کنید برای فایلی که می‌خواهید بارگیری کنید.

می‌توانید با پیوست کردن مسیرهای فرزند به ریشه Cloud Storage مخزن خود مرجعی ایجاد کنید، یا می‌توانید مرجعی از 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. بارگیری از نشانی وب
  2. بارگیری در آرایه بایت
  3. بارگیری با «جاری‌سازی»
  4. بارگیری در فایل محلی

روشی که برای بازیابی فایل‌هایتان استفاده می‌کنید به نحوه مصرف داده‌ها در بازی‌تان بستگی دارد.

بارگیری از نشانی وب

اگر می‌خواهید از نشانی وب با WWW یا UnityWebRequest Unity استفاده کنید، می‌توانید با فراخوانی 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 ذخیره شده‌اند.