تحميل الملفات باستخدام Cloud Storage لبرنامج Unity

Cloud Storage for Firebase تتيح لك تحميل الملفات بسرعة وسهولة إلى مساحة تخزين سحابي Cloud Storage تديرها Firebase وتوفّرها.

إنشاء مرجع

لتحميل ملف، عليك أولاً إنشاء مرجع Cloud Storage للملف الذي تريد تحميله.

يمكنك إنشاء مرجع من خلال إلحاق مسارات فرعية بالجذر في مساحة التخزين السحابي في Cloud Storage، أو يمكنك إنشاء مرجع من عنوان URL حالي بتنسيق `gs://` أو `https://` يشير إلى عنصر في Cloud Storage.Cloud StorageCloud Storagegs://https://

// 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);

لا يمكنك تحميل البيانات باستخدام مرجع يشير إلى جذر مساحة التخزين السحابي في Cloud Storage. يجب أن يشير المرجع إلى عنوان URL فرعي.

تحميل ملفات

بعد إنشاء مرجع، يمكنك تحميل الملفات إلى Cloud Storage بطريقتَين:

  1. التحميل من مصفوفة بايت في الذاكرة
  2. التحميل من مسار ملف يمثّل ملفًا على الجهاز

التحميل من البيانات في الذاكرة

الطريقة الأسهل لتحميل ملف إلى Cloud Storage هي استخدام طريقة PutBytesAsync(). PutBytesAsync() تأخذ مصفوفة بايت وتعرض 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> كدالة معاودة الاتصال لعلامات تقدُّم عملية التحميل.

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