העלאת קבצים באמצעות 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);

אי אפשר להעלות נתונים עם הפניה לרמה הבסיסית (root) של הקטגוריה ב-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.