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

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

ایجاد مرجع

برای بارگیری فایل، ابتدا مرجع Cloud Storage ایجاد کنید تا فایل موردنظرتان بارگیری شود.

می‌توانید با افزودن مسیرهای فرزند به ریشه Cloud Storage bucket، مرجع ایجاد کنید یا می‌توانید از gs:// یا https:// URL موجود که به شیء در 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 ذخیره شده‌اند، فراداده دریافت و به‌روز کنید.