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

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

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

ملاحظة: إذا كنت تستخدم الإصدار القديم من Google Drive API (الإصدار 2)، استخدِم المورد properties لإضافة خصائص إلى تطبيقك باستخدام properties.insert. للاطّلاع على قائمة كاملة بالاختلافات بين الإصدارَين، يُرجى الرجوع إلى مرجع مقارنة الإصدارَين 2 و3 من Drive API.

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

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

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

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

Drive API v2

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

التعامل مع خصائص الملفات المخصّصة

يوضّح هذا القسم كيفية تنفيذ بعض المهام المخصّصة المتعلقة بخصائص الملفات والتي تؤثر في جميع التطبيقات.

ملاحظة: لا تتضمّن واجهة مستخدم Google Drive طريقة مدمجة لتعديل الخصائص المخصّصة.

إضافة خصائص الملف المُخصَّصة أو تعديلها

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