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

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

ملاحظة: تتطلّب حزمة Cloud Storage for Firebase تلقائيًا من Firebase Authentication تنفيذ أي إجراء على بيانات الحزمة أو ملفاتها. يمكنك تغيير Firebase Security Rules إلى Cloud Storage لالسماح بالوصول غير المعتمَد في حالات معيّنة. ومع ذلك، في معظم الحالات، ننصحك بشدة بحظر الوصول وإعداد قواعد أمان صارمة (خاصةً للتطبيقات العلنية). يُرجى العِلم أنّه في حال استخدام Google App Engine وامتلاك حزمة Cloud Storage تلقائية بتنسيق اسم *.appspot.com، قد تحتاج إلى مراعاة تأثير قواعد الأمان في الوصول إلى ملفات App Engine.

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

تحتوي البيانات الوصفية للملف على سمات شائعة مثل 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);

معالجة الأخطاء

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

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

يمكنك تحديد بيانات وصفية مخصّصة باستخدام المَعلمة 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 الآنية الاستجابة) لتخزين هذا النوع من البيانات ومزامنته.

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

في ما يلي قائمة كاملة بخصائص البيانات الوصفية في ملف معيّن:

الموقع	النوع	هل يمكن ضبطها؟
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.