تنزيل الملفات باستخدام Cloud Storage for 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() ومرِّر معالج البث الخاص بك كمعلَمة أولى. سيتم استدعاء هذا العنصر النائب في سلسلة محادثات في الخلفية مع 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> الخاص بك كدالة ردّ لعلامات التقدّم.

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