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

בעזרת Cloud Storage for Firebase תוכלו להוריד במהירות ובקלות קבצים מקטגוריה (bucket) של Cloud Storage ש-Firebase מספקת ומנהלת.

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

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

אפשר ליצור הפניה על ידי צירוף נתיבים של צאצאים לשורש הקטגוריה Cloud Storage, או ליצור הפניה מכתובת URL קיימת מסוג gs:// או https:// שמפנה לאובייקט ב-Cloud Storage.

// Create a reference with an initial file path and name
StorageReference pathReference =
    storage.GetReference("images/stars.jpg");

// Create a reference from a Google Cloud Storage URI
StorageReference gsReference =
    storage.GetReferenceFromUrl("gs://bucket/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference httpsReference =
    storage.GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");

הורדת קבצים

אחרי שיוצרים קובץ עזר, אפשר להוריד קבצים מ-Cloud Storage בארבע דרכים:

  1. הורדה מכתובת URL
  2. הורדה למערך בייטים
  3. הורדה באמצעות סטרימינג
  4. הורדה לקובץ מקומי

השיטה שבה תשתמשו לאחזור הקבצים תלויה באופן שבו אתם רוצים לצרוך את הנתונים במשחק.

הורדה מכתובת URL

אם רוצים להשתמש בכתובת URL עם WWW או UnityWebRequest של Unity, אפשר לקבל כתובת URL להורדה של קובץ באמצעות קריאה ל-GetDownloadUrlAsync().

// Fetch the download URL
reference.GetDownloadUrlAsync().ContinueWithOnMainThread(task => {
    if (!task.IsFaulted && !task.IsCanceled) {
        Debug.Log("Download URL: " + task.Result);
        // ... now download the file via WWW or UnityWebRequest.
    }
});

הורדה למערך בייטים

אפשר להוריד את הקובץ למאגר בייטים בזיכרון באמצעות השיטה GetBytesAsync(). בשיטה הזו כל תוכן הקובץ יוטמע בזיכרון. אם מבקשים קובץ גדול יותר מהזיכרון הזמין באפליקציה, האפליקציה תקרוס. כדי למנוע בעיות זיכרון, חשוב להגדיר את הגודל המקסימלי לגודל שאתם יודעים שהאפליקציה יכולה לטפל בו, או להשתמש בשיטת הורדה אחרת.

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const long maxAllowedSize = 1 * 1024 * 1024;
reference.GetBytesAsync(maxAllowedSize).ContinueWithOnMainThread(task => {
    if (task.IsFaulted || task.IsCanceled) {
        Debug.LogException(task.Exception);
        // Uh-oh, an error occurred!
    }
    else {
        byte[] fileContents = task.Result;
        Debug.Log("Finished downloading!");
    }
});

הורדה באמצעות סטרימינג

הורדת הקובץ באמצעות Stream מאפשרת לכם לעבד את הנתונים בזמן הטעינה שלהם. כך תוכלו ליהנות מגמישות מקסימלית בטיפול בהורדה. קוראים ל-GetStreamAsync() ומעבירים את מעבד הנתונים שלכם כארגומנטים הראשונים. ה-delegate הזה יקרא בשרשור רקע עם Stream, שמאפשר לבצע פעולות או חישובים עם זמן אחזור ארוך, כמו אחסון התוכן בדיסק.

// Download via a Stream
reference.GetStreamAsync(stream => {
    // Do something with the stream here.
    //
    // This code runs on a background thread which reduces the impact
    // to your framerate.
    //
    // If you want to do something on the main thread, you can do that in the
    // progress eventhandler (second argument) or ContinueWith to execute it
    // at task completion.
}, null, CancellationToken.None);

GetStreamAsync() מקבלת ארגומנטים אופציונליים אחרי מעבד הסטרימינג, שמאפשרים לבטל את הפעולה או לקבל התראות על ההתקדמות.

הורדה לקובץ מקומי

השיטה GetFileAsync() מאפשרת להוריד קובץ ישירות למכשיר מקומי. משתמשים באפשרות הזו אם המשתמשים רוצים לגשת לקובץ במצב אופליין או לשתף אותו באפליקציה אחרת.

// Create local filesystem URL
string localUrl = "file:///local/images/island.jpg";

// Download to the local filesystem
reference.GetFileAsync(localUrl).ContinueWithOnMainThread(task => {
    if (!task.IsFaulted && !task.IsCanceled) {
        Debug.Log("File downloaded.");
    }
});

אפשר לצרף מאזינים להורדות כדי לעקוב אחרי התקדמות ההורדה. המאזין פועל לפי הממשק הסטנדרטי של System.IProgress<T>. אפשר להשתמש במופע של הכיתה StorageProgress כדי לספק Action<T> משלכם כפונקציית קריאה חוזרת (callback) לסימני התקדמות.

// Create local filesystem URL
string localUrl = "file:///local/images/island.jpg";

// Start downloading a file
Task task = reference.GetFileAsync(localFile,
    new StorageProgress<DownloadState>(state => {
        // called periodically during the download
        Debug.Log(String.Format(
            "Progress: {0} of {1} bytes transferred.",
            state.BytesTransferred,
            state.TotalByteCount
        ));
    }), CancellationToken.None);

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

טיפול בשגיאות

יש כמה סיבות לכך שעשויות להתרחש שגיאות בזמן ההורדה, כולל הקובץ לא קיים או שאין למשתמש הרשאה לגשת לקובץ הרצוי. מידע נוסף על שגיאות זמין בקטע טיפול בשגיאות במסמכי העזרה.

השלבים הבאים

אפשר גם לקבל ולעדכן מטא-נתונים של קבצים שמאוחסנים ב-Cloud Storage.