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

באמצעות Cloud Storage for Firebase אפשר להוריד קבצים במהירות ובקלות מקטגוריה של 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.