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

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

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

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

Web

import { getStorage, ref, getMetadata } from "firebase/storage";

// Create a reference to the file whose metadata we want to retrieve
const storage = getStorage();
const forestRef = ref(storage, 'images/forest.jpg');

// Get metadata properties
getMetadata(forestRef)
  .then((metadata) => {
    // Metadata now contains the metadata for 'images/forest.jpg'
  })
  .catch((error) => {
    // Uh-oh, an error occurred!
  });

Web

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

// Get metadata properties
forestRef.getMetadata()
  .then((metadata) => {
    // Metadata now contains the metadata for 'images/forest.jpg'
  })
  .catch((error) => {
    // Uh-oh, an error occurred!
  });

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

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

Web

import { getStorage, ref, updateMetadata } from "firebase/storage";

// Create a reference to the file whose metadata we want to change
const storage = getStorage();
const forestRef = ref(storage, 'images/forest.jpg');

// Create file metadata to update
const newMetadata = {
  cacheControl: 'public,max-age=300',
  contentType: 'image/jpeg'
};

// Update metadata properties
updateMetadata(forestRef, newMetadata)
  .then((metadata) => {
    // Updated metadata for 'images/forest.jpg' is returned in the Promise
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });

Web

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

// Create file metadata to update
var newMetadata = {
  cacheControl: 'public,max-age=300',
  contentType: 'image/jpeg'
};

// Update metadata properties
forestRef.updateMetadata(newMetadata)
  .then((metadata) => {
    // Updated metadata for 'images/forest.jpg' is returned in the Promise
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });

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

Web

import { getStorage, ref, updateMetadata } from "firebase/storage";

const storage = getStorage();
const forestRef = ref(storage, 'images/forest.jpg');

// Create file metadata with property to delete
const deleteMetadata = {
  contentType: null
};

// Delete the metadata property
updateMetadata(forestRef, deleteMetadata)
  .then((metadata) => {
    // metadata.contentType should be null
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });

Web

// Create file metadata with property to delete
var deleteMetadata = {
  contentType: null
};

// Delete the metadata property
forestRef.updateMetadata(deleteMetadata)
  .then((metadata) => {
    // metadata.contentType should be null
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });

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

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

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

يمكنك تحديد بيانات وصفية مخصّصة كعنصر يحتوي على سمات String.

Web

const metadata = {
  customMetadata: {
    'location': 'Yosemite, CA, USA',
    'activity': 'Hiking'
  }
};

Web

var metadata = {
  customMetadata: {
    'location': 'Yosemite, CA, USA',
    'activity': 'Hiking'
  }
};

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

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

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

الموقع النوع قابل للكتابة
bucket سلسلة لا
generation سلسلة لا
metageneration سلسلة لا
fullPath سلسلة لا
name سلسلة لا
size رقم لا
timeCreated سلسلة لا
updated سلسلة لا
md5Hash سلسلة نعم عند التحميل، لا عند تعديل البيانات الوصفية
cacheControl سلسلة نعم
contentDisposition سلسلة نعم
contentEncoding سلسلة نعم
contentLanguage سلسلة نعم
contentType سلسلة نعم
customMetadata عنصر يحتوي على عمليات ربط من سلسلة إلى سلسلة نعم

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