העלאת קבצים באמצעות Cloud Storage ל-Unity

Cloud Storage for Firebase מאפשרת להעלות קבצים במהירות ובקלות לקטגוריה Cloud Storage ש-Firebase מספקת ומנהלת.

יצירת קובץ עזר

כדי להעלות קובץ, קודם צריך ליצור הפניה Cloud Storage לקובץ שרוצים להעלות.

אפשר ליצור הפניה על ידי צירוף נתיבים של צאצאים לשורש הקטגוריה Cloud Storage, או ליצור הפניה מכתובת URL קיימת מסוג 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. ההפניה צריכה להפנות לכתובת URL של צאצא.

העלאת קבצים

אחרי שתיצרו קובץ עזר, תוכלו להעלות קבצים אל 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> משלכם כפונקציית קריאה חוזרת (callback) לסימני התקדמות.

// 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.