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

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

ایجاد مرجع

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

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

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

وقتی مرجع داشته باشید، می‌توانید فایل‌ها را به دو روش در 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 آشنا شویم.