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

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

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

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

Swift

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

// Get metadata properties
do {
  let metadata = try await forestRef.getMetadata()
} catch {
  // ...
}
    

Objective-C

// Create reference to the file whose metadata we want to retrieve
FIRStorageReference *forestRef = [storageRef child:@"images/forest.jpg"];

// Get metadata properties
[forestRef metadataWithCompletion:^(FIRStorageMetadata *metadata, NSError *error) {
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Metadata now contains the metadata for 'images/forest.jpg'
  }
}];
  

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

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

Swift

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

// Create file metadata to update
let newMetadata = StorageMetadata()
newMetadata.cacheControl = "public,max-age=300"
newMetadata.contentType = "image/jpeg"

// Update metadata properties
do {
  let updatedMetadata = try await forestRef.updateMetadata(newMetadata)
} catch {
  // ...
}
    

Objective-C

// Create reference to the file whose metadata we want to change
FIRStorageReference *forestRef = [storageRef child:@"images/forest.jpg"];

// Create file metadata to update
FIRStorageMetadata *newMetadata = [[FIRStorageMetadata alloc] init];
newMetadata.cacheControl = @"public,max-age=300";
newMetadata.contentType = @"image/jpeg";

// Update metadata properties
[forestRef updateMetadata:newMetadata completion:^(FIRStorageMetadata *metadata, NSError *error){
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Updated metadata for 'images/forest.jpg' is returned
  }
}];
  

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

Objective-C

FIRStorageMetadata *newMetadata = [[FIRStorageMetadata alloc] init];
newMetadata.contentType = nil;

// Delete the metadata property
[forestRef updateMetadata:newMetadata completion:^(FIRStorageMetadata *metadata, NSError *error){
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // metadata.contentType should be nil
  }
}];

Swift

let newMetadata = StorageMetadata()
newMetadata.contentType = nil

do {
  // Delete the metadata property
  let updatedMetadata = try await forestRef.updateMetadata(newMetadata)
} catch {
  // ...
}

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

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

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

يمكنك تحديد بيانات وصفية مخصّصة على أنّها NSDictionary تحتوي على خصائص NSString.

Swift

let metadata = [
  "customMetadata": [
    "location": "Yosemite, CA, USA",
    "activity": "Hiking"
  ]
]
    

Objective-C

NSDictionary *metadata = @{
  @"customMetadata": @{
    @"location": @"Yosemite, CA, USA",
    @"activity": @"Hiking"
  }
};

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

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

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

الموقع النوع قابل للكتابة
bucket سلسلة لا
generation سلسلة لا
metageneration سلسلة لا
fullPath سلسلة لا
name سلسلة لا
size Int64 لا
timeCreated التاريخ لا
updated التاريخ لا
md5Hash سلسلة نعم
cacheControl سلسلة نعم
contentDisposition سلسلة نعم
contentEncoding سلسلة نعم
contentLanguage سلسلة نعم
contentType سلسلة نعم
customMetadata [سلسلة: سلسلة] نعم

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