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

بعد تحميل ملف إلى مرجع 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().

Kotlin

// Create a storage reference from our app
val storageRef = storage.reference

// Get reference to the file
val forestRef = storageRef.child("images/forest.jpg")

forestRef.metadata.addOnSuccessListener { metadata ->
    // Metadata now contains the metadata for 'images/forest.jpg'
}.addOnFailureListener {
    // Uh-oh, an error occurred!
}
StorageActivity.kt

Java

// Create a storage reference from our app
StorageReference storageRef = storage.getReference();

// Get reference to the file
StorageReference forestRef = storageRef.child("images/forest.jpg");

forestRef.getMetadata().addOnSuccessListener(new OnSuccessListener<StorageMetadata>() {
    @Override
    public void onSuccess(StorageMetadata storageMetadata) {
        // Metadata now contains the metadata for 'images/forest.jpg'
    }
}).addOnFailureListener(new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception exception) {
        // Uh-oh, an error occurred!
    }
});
StorageActivity.java

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

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

Kotlin

// Create a storage reference from our app
val storageRef = storage.reference

// Get reference to the file
val forestRef = storageRef.child("images/forest.jpg")

// Create file metadata including the content type
val metadata = storageMetadata {
    contentType = "image/jpg"
    setCustomMetadata("myCustomProperty", "myValue")
}

// Update metadata properties
forestRef.updateMetadata(metadata).addOnSuccessListener { updatedMetadata ->
    // Updated metadata is in updatedMetadata
}.addOnFailureListener {
    // Uh-oh, an error occurred!
}
StorageActivity.kt

Java

// Create a storage reference from our app
StorageReference storageRef = storage.getReference();

// Get reference to the file
StorageReference forestRef = storageRef.child("images/forest.jpg");

// Create file metadata including the content type
StorageMetadata metadata = new StorageMetadata.Builder()
        .setContentType("image/jpg")
        .setCustomMetadata("myCustomProperty", "myValue")
        .build();

// Update metadata properties
forestRef.updateMetadata(metadata)
        .addOnSuccessListener(new OnSuccessListener<StorageMetadata>() {
            @Override
            public void onSuccess(StorageMetadata storageMetadata) {
                // Updated metadata is in storageMetadata
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                // Uh-oh, an error occurred!
            }
        });
StorageActivity.java

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

Kotlin

// Create file metadata with property to delete
val metadata = storageMetadata {
    contentType = null
}

// Delete the metadata property
forestRef.updateMetadata(metadata).addOnSuccessListener { updatedMetadata ->
    // updatedMetadata.contentType should be null
}.addOnFailureListener {
    // Uh-oh, an error occurred!
}
StorageActivity.kt

Java

// Create file metadata with property to delete
StorageMetadata metadata = new StorageMetadata.Builder()
        .setContentType(null)
        .build();

// Delete the metadata property
forestRef.updateMetadata(metadata)
        .addOnSuccessListener(new OnSuccessListener<StorageMetadata>() {
            @Override
            public void onSuccess(StorageMetadata storageMetadata) {
                // metadata.contentType should be null
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                // Uh-oh, an error occurred!
            }
        });
StorageActivity.java

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

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

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

يمكنك تحديد بيانات وصفية مخصّصة باستخدام طريقة setCustomMetadata() في الفئة StorageMetadata.Builder.

Kotlin

val metadata = storageMetadata {
    setCustomMetadata("location", "Yosemite, CA, USA")
    setCustomMetadata("activity", "Hiking")
}
StorageActivity.kt

Java

StorageMetadata metadata = new StorageMetadata.Builder()
        .setCustomMetadata("location", "Yosemite, CA, USA")
        .setCustomMetadata("activity", "Hiking")
        .build();
StorageActivity.java

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

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

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

إرجاع قيمة الخصائص	النوع	Setter Exists
getBucket	String	لا
getGeneration	String	لا
getMetadataGeneration	String	لا
getPath	String	لا
getName	String	لا
getSizeBytes	long	لا
getCreationTimeMillis	long	لا
getUpdatedTimeMillis	long	لا
getMd5Hash	String	لا
getCacheControl	String	نعم
getContentDisposition	String	نعم
getContentEncoding	String	نعم
getContentLanguage	String	نعم
getContentType	String	نعم
getCustomMetadata	String	نعم
getCustomMetadataKeys	Set<String>	لا

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