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

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

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

وتتضمّن البيانات الوصفية للملفات سمات شائعة، مثل 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 في الوقت الفعلي) لتخزين هذا النوع من البيانات ومزامنتها.

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

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

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

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