ویژگی های فایل سفارشی را اضافه کنید

ویژگی‌های فایل سفارشی جفت‌های کلید-مقدار هستند که برای ذخیره ابرداده‌های سفارشی برای یک فایل Google Drive (مانند برچسب‌ها)، شناسه‌های سایر فروشگاه‌های داده، اطلاعات به اشتراک گذاشته شده بین برنامه‌های گردش کار و غیره استفاده می‌شوند. به عنوان مثال، می توانید ویژگی های فایل را به تمام اسناد تولید شده توسط بخش فروش در Q1 اضافه کنید.

برای افزودن ویژگی های قابل مشاهده برای همه برنامه ها، از فیلد properties منبع files استفاده کنید. برای افزودن ویژگی های محدود به برنامه خود، از قسمت appProperties منبع files استفاده کنید.

از ویژگی ها می توان در عبارات جستجو نیز استفاده کرد.

این ساختار یک ویژگی معمولی است که ممکن است برای ذخیره شناسه پایگاه داده فایل Drive در فایل استفاده شود.

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

کار با ویژگی های فایل سفارشی

این بخش نحوه انجام برخی از وظایف مربوط به ویژگی فایل سفارشی که بر همه برنامه‌ها تأثیر می‌گذارد را توضیح می‌دهد.

ویژگی های فایل سفارشی را اضافه یا به روز کنید

برای افزودن یا به‌روزرسانی ویژگی‌های قابل مشاهده برای همه برنامه‌ها، از روش files.update برای تنظیم فیلد properties منبع files استفاده کنید.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

همچنین می‌توانید با استفاده از سرویس پیشرفته Drive در Google Apps Script، یک ویژگی سفارشی به فایل اضافه کنید. برای اطلاعات بیشتر، به افزودن خواص سفارشی مراجعه کنید.

ویژگی های فایل سفارشی را دریافت یا فهرست کنید

برای مشاهده ویژگی های قابل مشاهده برای همه برنامه ها، از روش files.get برای بازیابی ویژگی های فایل سفارشی برای فایل استفاده کنید.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

پاسخ شامل یک شیء properties است که شامل مجموعه ای از جفت های کلید-مقدار است.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

ویژگی های فایل سفارشی را حذف کنید

برای حذف مقادیر ویژگی قابل مشاهده برای همه برنامه‌ها، از روش files.update استفاده کنید تا فیلد properties منبع files را روی null قرار دهید.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "name": null
}

برای مشاهده تغییر، متد files.get را فراخوانی کنید تا شی properties فایل را بازیابی کنید.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

محدودیت ویژگی های فایل سفارشی

ویژگی های سفارشی دارای محدودیت های زیر هستند:

  • حداکثر 100 ویژگی سفارشی در هر فایل، مجموعاً از همه منابع.
  • حداکثر 30 ویژگی عمومی در هر فایل، مجموعاً از همه منابع.
  • حداکثر 30 ویژگی خصوصی در هر فایل از هر برنامه.
  • حداکثر 124 بایت در هر رشته ویژگی (شامل کلید و مقدار) در رمزگذاری UTF-8. به عنوان مثال، یک ویژگی با کلیدی که 10 کاراکتر طول دارد، فقط می تواند 114 کاراکتر در مقدار داشته باشد. به طور مشابه، خاصیتی که به 100 کاراکتر برای مقدار نیاز دارد، می تواند تا 24 کاراکتر برای کلید استفاده کند.

برای اطلاعات بیشتر به منبع files مراجعه کنید. برای Drive API v2، به منبع properties مراجعه کنید.

دسترسی به خصوصیات فایل سفارشی خصوصی

شما فقط می توانید ویژگی های خصوصی را با استفاده از فیلد appProperties از طریق یک درخواست احراز هویت که از یک نشانه دسترسی به دست آمده با شناسه مشتری OAuth 2.0 استفاده می کند، بازیابی کنید. شما نمی توانید از یک کلید API برای بازیابی ویژگی های خصوصی استفاده کنید.