تحميل الملفات باستخدام 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(). تم قطع string عن طريق PutFileAsync(). تمثل المسار إلى الملف وترجع 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