تحميل الملفات باستخدام Cloud Storage لبرنامج 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);

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

تحميل ملفات

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

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

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

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