استخدام البيانات الوصفية للملفات مع Cloud Storage على Android
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بعد تحميل ملف إلى مرجع Cloud Storage، يمكنك أيضًا الحصول على البيانات الوصفية للملف وتعديلها، مثلاً لعرض نوع المحتوى أو تعديله.
يمكن للملفات أيضًا تخزين أزواج مفاتيح/قيم مخصّصة مع بيانات وصفية إضافية للملفات.
تحتوي البيانات الوصفية للملف على سمات شائعة، مثل 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!
}
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!
}
});
يمكنك تعديل البيانات الوصفية للملف في أي وقت بعد اكتمال عملية تحميل الملف باستخدام طريقة 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!
}
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!
}
});
يمكنك حذف خصائص البيانات الوصفية القابلة للكتابة عن طريق تمرير 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!
}
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!
}
});
معالجة الأخطاء
هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء عند الحصول على البيانات الوصفية أو تعديلها، بما في ذلك عدم توفّر الملف أو عدم حصول المستخدم على إذن بالوصول إلى الملف المطلوب. يمكنك الاطّلاع على مزيد من المعلومات حول الأخطاء في قسم
التعامل مع الأخطاء
في المستندات.
يمكنك تحديد بيانات وصفية مخصّصة باستخدام طريقة setCustomMetadata()
في الفئة StorageMetadata.Builder
.
Kotlin
val metadata = storageMetadata {
setCustomMetadata("location", "Yosemite, CA, USA")
setCustomMetadata("activity", "Hiking")
}
Java
StorageMetadata metadata = new StorageMetadata.Builder()
.setCustomMetadata("location", "Yosemite, CA, USA")
.setCustomMetadata("activity", "Hiking")
.build();
يمكنك تخزين بيانات خاصة بالتطبيق لكل ملف في بيانات وصفية مخصّصة، ولكن ننصحك بشدة باستخدام قاعدة بيانات (مثل 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.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["\u003cbr /\u003e\n\nAfter uploading a file to Cloud Storage reference, you can also get\nand update the file metadata, for example to view or update the content type.\nFiles can also store custom key/value pairs with additional file metadata.\n| **Note:** By default, a Cloud Storage for Firebase bucket requires Firebase Authentication to perform any action on the bucket's data or files. You can change your Firebase Security Rules for Cloud Storage to [allow unauthenticated access for specific situations](/docs/storage/security/rules-conditions#public). However, for most situations, we strongly recommend [restricting access and setting up robust security rules](/docs/storage/security/get-started) (especially for production apps). Note that if you use Google App Engine and have a default Cloud Storage bucket with a name format of `*.appspot.com`, you may need to consider [how your security rules impact access to App Engine files](/docs/storage/gcp-integration#security-rules-and-app-engine-files).\n\nGet File Metadata\n\nFile metadata contains common properties such as `name`, `size`, and\n`contentType` (often referred to as MIME type) in addition to some less\ncommon ones like `contentDisposition` and `timeCreated`. This metadata can be\nretrieved from a Cloud Storage reference using\nthe `getMetadata()` method. \n\nKotlin \n\n```kotlin\n// Create a storage reference from our app\nval storageRef = storage.reference\n\n// Get reference to the file\nval forestRef = storageRef.child(\"images/forest.jpg\")\n``` \n\n```kotlin\nforestRef.metadata.addOnSuccessListener { metadata -\u003e\n // Metadata now contains the metadata for 'images/forest.jpg'\n}.addOnFailureListener {\n // Uh-oh, an error occurred!\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L345-L349\n```\n\nJava \n\n```java\n// Create a storage reference from our app\nStorageReference storageRef = storage.getReference();\n\n// Get reference to the file\nStorageReference forestRef = storageRef.child(\"images/forest.jpg\");\n``` \n\n```java\nforestRef.getMetadata().addOnSuccessListener(new OnSuccessListener\u003cStorageMetadata\u003e() {\n @Override\n public void onSuccess(StorageMetadata storageMetadata) {\n // Metadata now contains the metadata for 'images/forest.jpg'\n }\n}).addOnFailureListener(new OnFailureListener() {\n @Override\n public void onFailure(@NonNull Exception exception) {\n // Uh-oh, an error occurred!\n }\n});https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L437-L447\n```\n\nUpdate File Metadata\n\nYou can update file metadata at any time after the file upload completes by\nusing the `updateMetadata()` method. Refer to the\n[full list](#file-metadata-properties) for more information on what properties\ncan be updated. Only the properties specified in the metadata are updated,\nall others are left unmodified. \n\nKotlin \n\n```kotlin\n// Create a storage reference from our app\nval storageRef = storage.reference\n\n// Get reference to the file\nval forestRef = storageRef.child(\"images/forest.jpg\")\n``` \n\n```kotlin\n// Create file metadata including the content type\nval metadata = storageMetadata {\n contentType = \"image/jpg\"\n setCustomMetadata(\"myCustomProperty\", \"myValue\")\n}\n\n// Update metadata properties\nforestRef.updateMetadata(metadata).addOnSuccessListener { updatedMetadata -\u003e\n // Updated metadata is in updatedMetadata\n}.addOnFailureListener {\n // Uh-oh, an error occurred!\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L353-L364\n```\n\nJava \n\n```java\n// Create a storage reference from our app\nStorageReference storageRef = storage.getReference();\n\n// Get reference to the file\nStorageReference forestRef = storageRef.child(\"images/forest.jpg\");\n``` \n\n```java\n// Create file metadata including the content type\nStorageMetadata metadata = new StorageMetadata.Builder()\n .setContentType(\"image/jpg\")\n .setCustomMetadata(\"myCustomProperty\", \"myValue\")\n .build();\n\n// Update metadata properties\nforestRef.updateMetadata(metadata)\n .addOnSuccessListener(new OnSuccessListener\u003cStorageMetadata\u003e() {\n @Override\n public void onSuccess(StorageMetadata storageMetadata) {\n // Updated metadata is in storageMetadata\n }\n })\n .addOnFailureListener(new OnFailureListener() {\n @Override\n public void onFailure(@NonNull Exception exception) {\n // Uh-oh, an error occurred!\n }\n });https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L451-L470\n```\n\nYou can delete writable metadata properties by passing `null`: \n\nKotlin \n\n```kotlin\n// Create file metadata with property to delete\nval metadata = storageMetadata {\n contentType = null\n}\n\n// Delete the metadata property\nforestRef.updateMetadata(metadata).addOnSuccessListener { updatedMetadata -\u003e\n // updatedMetadata.contentType should be null\n}.addOnFailureListener {\n // Uh-oh, an error occurred!\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L374-L384\n```\n\nJava \n\n```java\n// Create file metadata with property to delete\nStorageMetadata metadata = new StorageMetadata.Builder()\n .setContentType(null)\n .build();\n\n// Delete the metadata property\nforestRef.updateMetadata(metadata)\n .addOnSuccessListener(new OnSuccessListener\u003cStorageMetadata\u003e() {\n @Override\n public void onSuccess(StorageMetadata storageMetadata) {\n // metadata.contentType should be null\n }\n })\n .addOnFailureListener(new OnFailureListener() {\n @Override\n public void onFailure(@NonNull Exception exception) {\n // Uh-oh, an error occurred!\n }\n });https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L480-L498\n```\n\nHandle Errors\n\nThere are a number of reasons why errors may occur on getting or updating\nmetadata, including the file not existing, or the user not having permission\nto access the desired file. More information on errors can be found in the\n[Handle Errors](/docs/storage/android/handle-errors)\nsection of the docs.\n\nCustom Metadata\n\nYou can specify custom metadata using the `setCustomMetadata()` method in the\n`StorageMetadata.Builder` class. \n\nKotlin \n\n```kotlin\nval metadata = storageMetadata {\n setCustomMetadata(\"location\", \"Yosemite, CA, USA\")\n setCustomMetadata(\"activity\", \"Hiking\")\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L390-L393\n```\n\nJava \n\n```java\nStorageMetadata metadata = new StorageMetadata.Builder()\n .setCustomMetadata(\"location\", \"Yosemite, CA, USA\")\n .setCustomMetadata(\"activity\", \"Hiking\")\n .build();https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L504-L507\n```\n\nYou can store app-specific data for each file in custom metadata, but we highly\nrecommend using a database (such as the\n[Firebase Realtime Database](/docs/database/android/start))\nto store and synchronize this type of data.\n\nFile Metadata Properties\n\nA full list of metadata properties on a file is available below:\n\n| Property Getter | Type | Setter Exists |\n|-------------------------|---------------|---------------|\n| `getBucket` | `String` | NO |\n| `getGeneration` | `String` | NO |\n| `getMetadataGeneration` | `String` | NO |\n| `getPath` | `String` | NO |\n| `getName` | `String` | NO |\n| `getSizeBytes` | `long` | NO |\n| `getCreationTimeMillis` | `long` | NO |\n| `getUpdatedTimeMillis` | `long` | NO |\n| `getMd5Hash` | `String` | NO |\n| `getCacheControl` | `String` | YES |\n| `getContentDisposition` | `String` | YES |\n| `getContentEncoding` | `String` | YES |\n| `getContentLanguage` | `String` | YES |\n| `getContentType` | `String` | YES |\n| `getCustomMetadata` | `String` | YES |\n| `getCustomMetadataKeys` | `Set\u003cString\u003e` | NO |\n\nUploading, downloading, and updating files is important, but so is being able\nto remove them. Let's learn how to\n[delete files](/docs/storage/android/delete-files)\nfrom Cloud Storage."]]