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

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

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

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

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

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

{
  '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"
  }
}

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

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

• حداکثر ۱۰۰ ویژگی سفارشی در هر فایل، که از همه منابع جمع‌آوری شده باشد.
• حداکثر ۳۰ ویژگی عمومی در هر فایل، که از همه منابع جمع‌آوری شده باشد.
• حداکثر 30 ویژگی خصوصی برای هر فایل از هر برنامه.
• حداکثر ۱۲۴ بایت برای هر رشته ویژگی (شامل کلید و مقدار) در کدگذاری UTF-8. برای مثال، یک ویژگی با کلید ۱۰ کاراکتری می‌تواند فقط ۱۱۴ کاراکتر در مقدار داشته باشد. به طور مشابه، یک ویژگی که برای مقدار به ۱۰۰ کاراکتر نیاز دارد، می‌تواند تا ۲۴ کاراکتر برای کلید استفاده کند.

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

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

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