تحميل الملفات باستخدام Cloud Storage for Unity

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

إنشاء مرجع

لتحميل ملف، قم أولاً بإنشاء مرجع 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);

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

تحميل الملفات

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

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

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

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