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

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

ملاحظة: بشكل تلقائي، تتطلّب حزمة 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+KTX

// 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+KTX

// 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+KTX

// 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+KTX

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) لتخزين هذا النوع من البيانات ومزامنته.

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

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

استرداد العقارات	النوع	توفُّر أداة الضبط
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.