إضافة خصائص ملف مخصصة

خصائص الملفات المخصّصة هي أزواج من المفاتيح والقيم تُستخدَم لتخزين بيانات وصفية مخصّصة لملف في Google Drive (مثل العلامات) ومعرّفات من مخازن بيانات أخرى ومعلومات تتم مشاركتها بين تطبيقات سير العمل وما إلى ذلك. على سبيل المثال، يمكنك إضافة سمات ملف إلى جميع المستندات التي أنشأها قسم المبيعات في الربع الأول.

لإضافة خصائص مرئية لجميع التطبيقات، استخدِم الحقل properties الخاص بمورد files. لإضافة سمات مقصورة على تطبيقك، استخدِم الحقل appProperties الخاص بمورد files.

يمكن أيضًا استخدام السمات في عبارات البحث.

هذا هو بنية سمة نموذجية يمكن استخدامها لتخزين معرّف قاعدة بيانات ملف Drive في الملف.

الإصدار 3 من Drive API

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

الإصدار 2 من Drive API

{
  '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". لمزيد من المعلومات، اطّلِع على إضافة خصائص مخصّصة.

الحصول على خصائص الملف المخصّصة أو إدراجها

لعرض خصائص الملفات المرئية لجميع التطبيقات، استخدِم طريقة 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. لا يمكنك استخدام مفتاح واجهة برمجة التطبيقات لاسترداد المواقع الخاصة.