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

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

ایجاد مرجع

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

می‌توانید با پیوست کردن مسیرهای فرزند به ریشه Cloud Storage مخزن خود مرجعی ایجاد کنید، یا می‌توانید مرجعی از gs:// یا https:// نشانی وب موجود که به شیئی در Cloud Storage ارجاع می‌دهد ایجاد کنید.

// Create a root reference
StorageReference storageRef = storage.RootReference;

// Create a reference to "mountains.jpg"
StorageReference mountainsRef = storageRef.Child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
StorageReference mountainImagesRef =
    storageRef.Child("images/mountains.jpg");

// While the file names are the same, the references point to different files
Assert.AreEqual(mountainsRef.Name, mountainImagesRef.Name);
Assert.AreNotEqual(mountainsRef.Path, mountainImagesRef.Path);

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

بارگذاری فایل‌ها

پس‌از اینکه مرجعی داشتید، می‌توانید فایل‌ها را به Cloud Storage به دو روش بارگذاری کنید:

  1. بارگذاری از آرایه بایت در حافظه
  2. بارگذاری از مسیر فایلی که نشان‌دهنده فایلی در دستگاه است

بارگذاری از داده‌های موجود در حافظه

روش PutBytesAsync() ساده‌ترین راه برای بارگذاری فایل در Cloud Storage است. ‫PutBytesAsync() یک byte[]‎ می‌گیرد و یک System.Task<Firebase.Storage.StorageMetadata> برمی‌گرداند که وقتی تکلیف تکمیل می‌شود حاوی اطلاعاتی درباره فایل خواهد بود. می‌توانید به‌صورت اختیاری از IProgress<UploadState> (معمولاً StorageProgress<UploadState>) برای نظارت بر وضعیت بارگذاری خود استفاده کنید.

// Data in memory
var customBytes = new byte[] {
    /*...*/
};

// Create a reference to the file you want to upload
StorageReference riversRef = storageRef.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
riversRef.PutBytesAsync(customBytes)
    .ContinueWith((Task<StorageMetadata> task) => {
        if (task.IsFaulted || task.IsCanceled) {
            Debug.Log(task.Exception.ToString());
            // Uh-oh, an error occurred!
        }
        else {
            // Metadata contains file metadata such as size, content-type, and md5hash.
            StorageMetadata metadata = task.Result;
            string md5Hash = metadata.Md5Hash;
            Debug.Log("Finished uploading...");
            Debug.Log("md5 hash = " + md5Hash);
        }
    });

بارگذاری از فایل محلی

می‌توانید فایل‌های محلی در دستگاه‌ها، مانند عکس‌ها و ویدیوهای دوربین، را با روش PutFileAsync() بارگذاری کنید. ‫PutFileAsync() یک string می‌گیرد که نشان‌دهنده مسیر فایل است و یک System.Task<Firebase.Storage.StorageMetadata> برمی‌گرداند که وقتی کار تکمیل می‌شود حاوی اطلاعاتی درباره فایل است. می‌توانید به‌صورت اختیاری از IProgress<UploadState> (معمولاً StorageProgress<UploadState>) برای نظارت بر وضعیت بارگذاری خود استفاده کنید.

// File located on disk
string localFile = "...";

// Create a reference to the file you want to upload
StorageReference riversRef = storageRef.Child("images/rivers.jpg");

// Upload the file to the path "images/rivers.jpg"
riversRef.PutFileAsync(localFile)
    .ContinueWith((Task<StorageMetadata> task) => {
        if (task.IsFaulted || task.IsCanceled) {
            Debug.Log(task.Exception.ToString());
            // Uh-oh, an error occurred!
        }
        else {
            // Metadata contains file metadata such as size, content-type, and download URL.
            StorageMetadata metadata = task.Result;
            string md5Hash = metadata.Md5Hash;
            Debug.Log("Finished uploading...");
            Debug.Log("md5 hash = " + md5Hash);
        }
    });

اگر می‌خواهید بارگذاری خود را به‌طور فعال نظارت کنید، می‌توانید از یک کلاس StorageProgress یا کلاس خودتان که IProgress<UploadState> را با روش‌های PutFileAsync() یا PutBytesAsync() پیاده‌سازی می‌کند استفاده کنید. برای اطلاعات بیشتر، مدیریت بارگذاری‌ها را ببینید.

افزودن فراداده فایل

همچنین می‌توانید هنگام بارگذاری فایل‌ها، فراداده اضافه کنید. این فراداده شامل ویژگی‌های معمول فراداده فایل مانند Name، Size، و ContentType (که معمولاً به‌عنوان نوع MIME شناخته می‌شود) است. روش PutFileAsync() به‌طور خودکار نوع محتوا را از پسوند نام فایل استنباط می‌کند، اما می‌توانید با مشخص کردن ContentType در فراداده، نوع تشخیص داده‌شده خودکار را لغو کنید. اگر ContentType ارائه نکنید و Cloud Storage نتواند پیش‌فرضی را از پسوند فایل استنباط کند، Cloud Storage از application/octet-stream استفاده می‌کند. برای اطلاعات بیشتر درباره فراداده فایل، به بخش استفاده از فراداده فایل مراجعه کنید.

// Create storage reference
StorageReference mountainsRef = storageRef.Child("images/mountains.jpg");

byte[] customBytes = new byte[] {
    /*...*/
};
string localFile = "...";

// Create file metadata including the content type
var newMetadata = new MetadataChange();
newMetadata.ContentType = "image/jpeg";

// Upload data and metadata
mountainsRef.PutBytesAsync(customBytes, newMetadata, null,
    CancellationToken.None); // .ContinueWithOnMainThread(...
// Upload file and metadata
mountainsRef.PutFileAsync(localFile, newMetadata, null,
    CancellationToken.None); // .ContinueWithOnMainThread(...

نظارت بر پیشرفت بارگذاری

می‌توانید شنوندگان را به بارگذاری‌ها پیوست کنید تا پیشرفت بارگذاری را نظارت کنید. شنونده از رابط استاندارد System.IProgress<T> پیروی می‌کند. می‌توانید از نمونه کلاس StorageProgress برای ارائه Action<T> خودتان به‌عنوان بازخوانی برای تیک‌های پیشرفت استفاده کنید.

// Start uploading a file
var task = storageRef.Child("images/mountains.jpg")
    .PutFileAsync(localFile, null,
        new StorageProgress<UploadState>(state => {
            // called periodically during the upload
            Debug.Log(String.Format("Progress: {0} of {1} bytes transferred.",
                state.BytesTransferred, state.TotalByteCount));
        }), CancellationToken.None, null);

task.ContinueWithOnMainThread(resultTask => {
    if (!resultTask.IsFaulted && !resultTask.IsCanceled) {
        Debug.Log("Upload finished.");
    }
});

مدیریت کردن خطا

دلایل متعددی وجود دارد که ممکن است خطاها در بارگذاری رخ دهند، ازجمله عدم وجود فایل محلی، یا نداشتن اجازه کاربر برای بارگذاری فایل موردنظر. می‌توانید اطلاعات بیشتری درباره خطاها در بخش مدیریت خطاها سندنگارها پیدا کنید.

مراحل بعدی

اکنون که فایل‌ها را بارگذاری کرده‌اید، بیایید با نحوه بارگیری آن‌ها از Cloud Storage آشنا شویم.