استخدام البيانات الوصفية للملفات مع Cloud Storage لـ C++
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بعد تحميل ملف إلى مرجع Cloud Storage، يمكنك أيضًا الحصول على البيانات الوصفية للملف وتعديلها، مثلاً لتعديل نوع المحتوى. يمكن للملفات أيضًا تخزين أزواج المفاتيح والقيم المخصّصة مع بيانات وصفية إضافية للملفات.
الحصول على البيانات الوصفية للملف
تحتوي البيانات الوصفية للملف على خصائص شائعة مثل name وsize وcontent_type (يُشار إليها غالبًا باسم نوع MIME)، بالإضافة إلى بعض الخصائص الأقل شيوعًا مثل content_disposition وtime_created. يمكن استرداد هذه البيانات الوصفية من Cloud Storage مرجع باستخدام طريقة GetMetadata.
// Create reference to the file whose metadata we want to retrieveStorageReferenceforest_ref=storage_ref.Child("images/forest.jpg");// Get metadata propertiesFuturefuture=forest_ref.GetMetadata();// Wait for Future to complete...if(future.Error()!=firebase::storage::kErrorNone){// Uh-oh, an error occurred!}else{// We can now retrieve the metadata for 'images/forest.jpg'Metadata*metadata=future.Result();}
تعديل البيانات الوصفية للملف
يمكنك تعديل البيانات الوصفية للملف في أي وقت بعد اكتمال عملية تحميل الملف باستخدام طريقة UpdateMetadata. راجِع القائمة الكاملة للحصول على مزيد من المعلومات حول المواقع التي يمكن تعديلها. يتم تعديل السمات المحدّدة في البيانات الوصفية فقط، وتبقى جميع السمات الأخرى بدون تعديل.
// Create reference to the file whose metadata we want to changefirebase::storage::StorageReferenceforest_ref=storage_ref.child("images/forest.jpg");// Create file metadata to updateMetadatanew_metadata;newMetadata.set_cache_control("public,max-age=300");newMetadata.set_content_type("image/jpeg");// Update metadata propertiesFuturefuture=forest_ref.UpdateMetadata(new_metadata);// Wait for Future to complete...if(future.Error()!=firebase::storage::kErrorNone){// Uh-oh, an error occurred!}else{// We can now retrieve the updated metadata for 'images/forest.jpg'Metadata*metadata=future.Result();}
يمكنك حذف خصائص البيانات الوصفية القابلة للكتابة عن طريق تمرير السلسلة الفارغة:
// Create file metadata with property to deleteStorageMetadatanew_metadata;new_metadata.set_content_type("");// Delete the metadata propertyFuturefuture=forest_ref.UpdateMetadata(new_metadata);// Wait for Future to complete...if(future.Error()!=0){// Uh-oh, an error occurred!}else{// metadata.content_type() should be an empty stringMetadata*metadata=future.Result();}
معالجة الأخطاء
هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء عند الحصول على البيانات الوصفية أو تعديلها، بما في ذلك عدم توفّر الملف أو عدم حصول المستخدم على إذن بالوصول إلى الملف المطلوب. يمكنك الاطّلاع على مزيد من المعلومات حول الأخطاء في قسم
التعامل مع الأخطاء
في المستندات.
البيانات الوصفية المخصّصة
يمكنك تحديد بيانات وصفية مخصّصة كـ std::map تحتوي على سمات std::string.
std::map<std::string,std::string>*custom_metadata=metadata.custom_metadata();custom_metadata->insert(std::make_pair("location","Yosemite, CA, USA");custom_metadata->insert(std::make_pair("activity","Hiking");
يمكنك تخزين بيانات خاصة بالتطبيق لكل ملف في بيانات وصفية مخصّصة، ولكن ننصحك بشدة باستخدام قاعدة بيانات (مثل Firebase Realtime Database) لتخزين هذا النوع من البيانات ومزامنته.
خصائص البيانات الوصفية للملف
في ما يلي قائمة كاملة بخصائص البيانات الوصفية في ملف:
الموقع
النوع
قابل للكتابة
bucket
const char*
لا
generation
const char*
لا
metageneration
const char*
لا
full_path
const char*
لا
name
const char*
لا
size
int64_t
لا
time_created
int64_t
لا
updated
int64_t
لا
cache_control
const char*
نعم
content_disposition
const char*
نعم
content_encoding
const char*
نعم
content_language
const char*
نعم
content_type
const char*
نعم
download_urls
std::vector<std::string>
لا
custom_metadata
std::map<std::string, std::string>
نعم
الخطوات التالية
إنّ تحميل الملفات وتنزيلها وتعديلها مهم، ولكن من المهم أيضًا أن تتمكّن من إزالتها. لنتعرّف على كيفية
حذف الملفات
من Cloud Storage.
تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-09-03 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["\u003cbr /\u003e\n\nAfter uploading a file to Cloud Storage reference, you can also get\nand update the file metadata, for example to update the content type. Files\ncan 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`content_type` (often referred to as MIME type) in addition to some less common\nones like `content_disposition` and `time_created`. This metadata can be\nretrieved from a Cloud Storage reference using the `GetMetadata`\nmethod. \n\n```c++\n// Create reference to the file whose metadata we want to retrieve\nStorageReference forest_ref = storage_ref.Child(\"images/forest.jpg\");\n\n// Get metadata properties\nFuture future = forest_ref.GetMetadata();\n\n// Wait for Future to complete...\n\nif (future.Error() != firebase::storage::kErrorNone) {\n // Uh-oh, an error occurred!\n} else {\n // We can now retrieve the metadata for 'images/forest.jpg'\n Metadata* metadata = future.Result();\n}\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\n```c++\n// Create reference to the file whose metadata we want to change\nfirebase::storage::StorageReference forest_ref = storage_ref.child(\"images/forest.jpg\");\n\n// Create file metadata to update\nMetadata new_metadata;\nnewMetadata.set_cache_control(\"public,max-age=300\");\nnewMetadata.set_content_type(\"image/jpeg\");\n\n// Update metadata properties\nFuture future = forest_ref.UpdateMetadata(new_metadata);\n\n// Wait for Future to complete...\n\nif (future.Error() != firebase::storage::kErrorNone) {\n // Uh-oh, an error occurred!\n} else {\n // We can now retrieve the updated metadata for 'images/forest.jpg'\n Metadata* metadata = future.Result();\n}\n```\n\nYou can delete writable metadata properties by passing the empty string: \n\n```c++\n// Create file metadata with property to delete\nStorageMetadata new_metadata;\nnew_metadata.set_content_type(\"\");\n\n// Delete the metadata property\nFuture future = forest_ref.UpdateMetadata(new_metadata);\n\n// Wait for Future to complete...\n\nif (future.Error() != 0) {\n // Uh-oh, an error occurred!\n} else {\n // metadata.content_type() should be an empty string\n Metadata* metadata = future.Result();\n}\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/cpp/handle-errors)\nsection of the docs.\n\nCustom Metadata\n\nYou can specify custom metadata as an `std::map` containing `std::string`\nproperties. \n\n```c++\nstd::map\u003cstd::string, std::string\u003e* custom_metadata = metadata.custom_metadata();\ncustom_metadata-\u003einsert(std::make_pair(\"location\", \"Yosemite, CA, USA\");\ncustom_metadata-\u003einsert(std::make_pair(\"activity\", \"Hiking\");\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)) 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 | Writable |\n|-----------------------|--------------------------------------|----------|\n| `bucket` | const char\\* | NO |\n| `generation` | const char\\* | NO |\n| `metageneration` | const char\\* | NO |\n| `full_path` | const char\\* | NO |\n| `name` | const char\\* | NO |\n| `size` | int64_t | NO |\n| `time_created` | int64_t | NO |\n| `updated` | int64_t | NO |\n| `cache_control` | const char\\* | YES |\n| `content_disposition` | const char\\* | YES |\n| `content_encoding` | const char\\* | YES |\n| `content_language` | const char\\* | YES |\n| `content_type` | const char\\* | YES |\n| `download_urls` | std::vector\\\u003cstd::string\\\u003e | NO |\n| `custom_metadata` | std::map\\\u003cstd::string, std::string\\\u003e | YES |\n\nNext Steps\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/cpp/delete-files)\nfrom Cloud Storage."]]
