بعد تحميل ملف إلى مرجع Cloud Storage، يمكنك أيضًا الحصول على البيانات الوصفية للملف وتعديلها، مثلاً لعرض نوع المحتوى أو تعديله.
يمكن للملفات أيضًا تخزين أزواج مفاتيح/قيم مخصّصة مع بيانات وصفية إضافية للملفات.
الحصول على البيانات الوصفية للملف
تحتوي البيانات الوصفية للملف على سمات شائعة، مثل name وsize وcontentType (يُشار إليها غالبًا باسم نوع MIME)، بالإضافة إلى بعض السمات الأقل شيوعًا، مثل contentDisposition وtimeCreated. يمكن استرداد هذه البيانات الوصفية من مرجع Cloud Storage باستخدام الطريقة getMetadata().
// Create reference to the file whose metadata we want to retrievefinalforestRef=storageRef.child("images/forest.jpg");// Get metadata propertiesfinalmetadata=awaitforestRef.getMetadata();// Metadata now contains the metadata for 'images/forest.jpg'
تعديل البيانات الوصفية للملف
يمكنك تعديل البيانات الوصفية للملف في أي وقت بعد اكتمال عملية تحميل الملف باستخدام طريقة updateMetadata(). راجِع القائمة الكاملة للحصول على مزيد من المعلومات حول المواقع التي يمكن تعديلها. يتم تعديل السمات المحدّدة في البيانات الوصفية فقط، وتبقى جميع السمات الأخرى بدون تعديل.
// Create reference to the file whose metadata we want to changefinalforestRef=storageRef.child("images/forest.jpg");// Create file metadata to updatefinalnewMetadata=SettableMetadata(cacheControl:"public,max-age=300",contentType:"image/jpeg",);// Update metadata propertiesfinalmetadata=awaitforestRef.updateMetadata(newMetadata);// Updated metadata for 'images/forest.jpg' is returned
يمكنك حذف خصائص البيانات الوصفية القابلة للكتابة عن طريق تمرير null:
// Delete the cacheControl propertyfinalnewMetadata=SettableMetadata(cacheControl:null);finalmetadata=awaitforestRef.updateMetadata(newMetadata);
معالجة الأخطاء
هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء عند الحصول على البيانات الوصفية أو تعديلها، بما في ذلك عدم توفّر الملف أو عدم حصول المستخدم على إذن بالوصول إلى الملف المطلوب. يمكنك الاطّلاع على مزيد من المعلومات حول الأخطاء في قسم التعامل مع الأخطاء ضمن المستندات.
البيانات الوصفية المخصّصة
يمكنك تحديد بيانات وصفية مخصّصة باستخدام المَعلمة customMetadata في الدالة الإنشائية SettableMetadata:
// Create reference to the file whose metadata we want to changefinalforestRef=storageRef.child("images/forest.jpg");// Create file metadata to updatefinalnewCustomMetadata=SettableMetadata(customMetadata:{"location":"Yosemite, CA, USA","activity":"Hiking",},);// Update metadata propertiesfinalmetadata=awaitforestRef.updateMetadata(newCustomMetadata);// Updated metadata for 'images/forest.jpg' is returned
يمكنك تخزين بيانات خاصة بالتطبيق لكل ملف في بيانات وصفية مخصّصة، ولكننا ننصحك بشدة باستخدام قاعدة بيانات (مثل قاعدة بيانات Firebase الآنية الاستجابة) لتخزين هذا النوع من البيانات ومزامنته.
خصائص البيانات الوصفية للملف
في ما يلي قائمة كاملة بخصائص البيانات الوصفية في ملف:
الموقع
النوع
قابلة للضبط؟
bucket
String
لا
generation
String
لا
metageneration
String
لا
metadataGeneration
String
لا
fullPath
String
لا
name
String
لا
size
int
لا
timeCreated
DateTime
لا
updated
DateTime
لا
md5Hash
String
لا
cacheControl
String
نعم
contentDisposition
String
نعم
contentEncoding
String
نعم
contentLanguage
String
نعم
contentType
String
نعم
customMetadata
Map<String, String>
نعم
إنّ تحميل الملفات وتنزيلها وتعديلها مهم، ولكن من المهم أيضًا أن تتمكّن من إزالتها. لنتعرّف على كيفية حذف الملفات
من Cloud Storage.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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\n // Create reference to the file whose metadata we want to retrieve\n final forestRef = storageRef.child(\"images/forest.jpg\");\n\n // Get metadata properties\n final metadata = await forestRef.getMetadata();\n\n // Metadata now contains the metadata for 'images/forest.jpg'\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\n // Create reference to the file whose metadata we want to change\n final forestRef = storageRef.child(\"images/forest.jpg\");\n\n // Create file metadata to update\n final newMetadata = SettableMetadata(\n cacheControl: \"public,max-age=300\",\n contentType: \"image/jpeg\",\n );\n\n // Update metadata properties\n final metadata = await forestRef.updateMetadata(newMetadata);\n\n // Updated metadata for 'images/forest.jpg' is returned\n\nYou can delete writable metadata properties by passing `null`: \n\n // Delete the cacheControl property\n final newMetadata = SettableMetadata(cacheControl: null);\n final metadata = await forestRef.updateMetadata(newMetadata);\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/flutter/handle-errors) section of the docs.\n\nCustom Metadata\n\nYou can specify custom metadata using the `customMetadata` parameter of the\n`SettableMetadata` constructor: \n\n // Create reference to the file whose metadata we want to change\n final forestRef = storageRef.child(\"images/forest.jpg\");\n\n // Create file metadata to update\n final newCustomMetadata = SettableMetadata(\n customMetadata: {\n \"location\": \"Yosemite, CA, USA\",\n \"activity\": \"Hiking\",\n },\n );\n\n // Update metadata properties\n final metadata = await forestRef.updateMetadata(newCustomMetadata);\n\n // Updated metadata for 'images/forest.jpg' is returned\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/overview)) to store and synchronize this type of\ndata.\n\nFile Metadata Properties\n\nA full list of metadata properties on a file is available below:\n\n| Property | Type | Settable? |\n|----------------------|-----------------------|-----------|\n| `bucket` | `String` | No |\n| `generation` | `String` | No |\n| `metageneration` | `String` | No |\n| `metadataGeneration` | `String` | No |\n| `fullPath` | `String` | No |\n| `name` | `String` | No |\n| `size` | `int` | No |\n| `timeCreated` | `DateTime` | No |\n| `updated` | `DateTime` | No |\n| `md5Hash` | `String` | No |\n| `cacheControl` | `String` | Yes |\n| `contentDisposition` | `String` | Yes |\n| `contentEncoding` | `String` | Yes |\n| `contentLanguage` | `String` | Yes |\n| `contentType` | `String` | Yes |\n| `customMetadata` | `Map\u003cString, String\u003e` | Yes |\n\nUploading, downloading, and updating files is important, but so is being able\nto remove them. Let's learn how to [delete files](/docs/storage/flutter/delete-files)\nfrom Cloud Storage."]]