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

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

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

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

واجهة برمجة التطبيقات Web modular API

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!
  });
storage_get_metadata.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

// 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!
  });
file-metadata.js

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

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

واجهة برمجة التطبيقات Web modular API

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!
  });
storage_update_metadata.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

// 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!
  });
file-metadata.js

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

واجهة برمجة التطبيقات Web modular API

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!
  });
storage_delete_metadata.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

// 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!
  });
file-metadata.js

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

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

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

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

واجهة برمجة التطبيقات Web modular API

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

واجهة برمجة التطبيقات لمساحة الاسم على الويب

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

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

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

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

الموقع Type قابلة للكتابة
bucket سلسلة لا
generation سلسلة لا
metageneration سلسلة لا
fullPath سلسلة لا
name سلسلة لا
size عدد لا
timeCreated سلسلة لا
updated سلسلة لا
md5Hash سلسلة نعم عند التحميل، لا على updateMetadata
cacheControl سلسلة نعم
contentDisposition سلسلة نعم
contentEncoding سلسلة نعم
contentLanguage سلسلة نعم
contentType سلسلة نعم
customMetadata كائن يحتوي على تعيينات السلسلة->السلاسل نعم

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