تتيح لك 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 بطريقتَين:
- التحميل من مصفوفة بايت في الذاكرة
- التحميل من مسار ملف يمثّل ملفًا على الجهاز
التحميل من البيانات في الذاكرة
طريقة 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.