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

בדף הזה מוסבר איך להשתמש ב-SDK של Cloud Storage for Firebase כדי להעלות קבצים לקטגוריה של Cloud Storage.

מידע נוסף זמין בשאלות הנפוצות האלה.

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

כדי להעלות קובץ, קודם צריך ליצור הפניה מסוג 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 מסיקה באופן אוטומטי את סוג ה-MIME מסיומת שם הקובץ, אבל אפשר לשנות את הסוג שזוהה אוטומטית על ידי ציון 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.