دانلود فایل ها با Cloud Storage for Unity

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

ایجاد یک مرجع

برای دانلود یک فایل، ابتدا یک مرجع 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. دانلود از یک URL
  2. دانلود به یک آرایه بایتی
  3. دانلود با استریم
  4. دانلود در یک فایل محلی

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

دانلود از یک URL

اگر می‌خواهید از یک URL با WWW یا UnityWebRequest یونیتی استفاده کنید، می‌توانید با فراخوانی GetDownloadUrlAsync() یک URL دانلود برای یک فایل دریافت کنید.

// 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!");
    }
});

دانلود از طریق استریم

دانلود فایل با یک Stream به شما این امکان را می‌دهد که داده‌ها را همزمان با بارگذاری پردازش کنید. این کار حداکثر انعطاف‌پذیری را در هنگام مدیریت دانلود به شما می‌دهد. GetStreamAsync() را فراخوانی کنید و پردازنده جریان خود را به عنوان اولین آرگومان ارسال کنید. این delegate در یک thread پس‌زمینه با یک 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> خود به عنوان یک callback برای تیک‌های پیشرفت استفاده کنید.

// 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 ذخیره شده‌اند را دریافت و به‌روزرسانی کنید .