استخدام البيانات الوصفية للملفات مع Cloud Storage على Flutter

بعد تحميل ملف إلى مرجع Cloud Storage، يمكنك أيضًا الحصول على البيانات الوصفية للملف وتعديلها، على سبيل المثال لعرض نوع المحتوى أو تعديله. يمكن لتطبيق Files أيضًا تخزين أزواج مفاتيح/قيم مخصّصة مع بيانات وصفية إضافية للملفات.

الحصول على البيانات الوصفية للملف

وتتضمّن البيانات الوصفية للملفات سمات شائعة، مثل name وsize وcontentType (يُشار إليها غالبًا باسم نوع MIME)، بالإضافة إلى بعض السمات الأقل شيوعًا، مثل contentDisposition وtimeCreated. يمكن استرداد هذه البيانات الوصفية من مرجع Cloud Storage باستخدام طريقة getMetadata().

// Create reference to the file whose metadata we want to retrieve
final forestRef = storageRef.child("images/forest.jpg");

// Get metadata properties
final metadata = await forestRef.getMetadata();

// Metadata now contains the metadata for 'images/forest.jpg'

تعديل البيانات الوصفية للملف

يمكنك تعديل البيانات الوصفية للملف في أيّ وقت بعد اكتمال تحميل الملف باستخدام الطريقة updateMetadata(). يُرجى الرجوع إلى القائمة الكاملة لمزيد من المعلومات حول السمات التي يمكن تعديلها. يتم فقط تحديث الخصائص المحددة في بيانات التعريف، وتترك جميع الخصائص الأخرى بدون تعديل.

// Create reference to the file whose metadata we want to change
final forestRef = storageRef.child("images/forest.jpg");

// Create file metadata to update
final newMetadata = SettableMetadata(
  cacheControl: "public,max-age=300",
  contentType: "image/jpeg",
);

// Update metadata properties
final metadata = await forestRef.updateMetadata(newMetadata);

// Updated metadata for 'images/forest.jpg' is returned

يمكنك حذف سمات البيانات الوصفية القابلة للكتابة من خلال ضبط null على:

// Delete the cacheControl property
final newMetadata = SettableMetadata(cacheControl: null);
final metadata = await forestRef.updateMetadata(newMetadata);

التعامل مع الأخطاء

قد تحدث أخطاء عند الحصول على البيانات الوصفية أو تعديلها لأسباب عديدة، منها عدم توفّر الملف أو عدم منح المستخدم الإذن بالوصول إلى الملف المطلوب. يمكن العثور على مزيد من المعلومات حول الأخطاء في قسم معالجة الأخطاء في المستندات.

البيانات الوصفية المخصّصة

يمكنك تحديد البيانات الوصفية المخصّصة باستخدام معلَمة customMetadata في الدالة الإنشائية SettableMetadata:

// Create reference to the file whose metadata we want to change
final forestRef = storageRef.child("images/forest.jpg");

// Create file metadata to update
final newCustomMetadata = SettableMetadata(
  customMetadata: {
    "location": "Yosemite, CA, USA",
    "activity": "Hiking",
  },
);

// Update metadata properties
final metadata = await forestRef.updateMetadata(newCustomMetadata);

// Updated metadata for 'images/forest.jpg' is returned

يمكنك تخزين بيانات خاصة بالتطبيق لكل ملف في البيانات الوصفية المخصّصة، ولكن ننصحك بشدة باستخدام قاعدة بيانات (مثل قاعدة بيانات Firebase في الوقت الفعلي) لتخزين هذا النوع من البيانات ومزامنتها.

خصائص البيانات الوصفية للملفات

تتوفر قائمة كاملة بسمات البيانات الوصفية في ملف أدناه:

الموقع	Type	قابل للضبط؟
bucket	String	لا
generation	String	لا
metageneration	String	لا
metadataGeneration	String	لا
fullPath	String	لا
name	String	لا
size	int	لا
timeCreated	DateTime	لا
updated	DateTime	لا
md5Hash	String	لا
cacheControl	String	نعم
contentDisposition	String	نعم
contentEncoding	String	نعم
contentLanguage	String	نعم
contentType	String	نعم
customMetadata	Map<String, String>	نعم

من المهم تحميل الملفات وتنزيلها وتحديثها، وكذلك القدرة على إزالتها. لنتعرّف على كيفية حذف الملفات من Cloud Storage.