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

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

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

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

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

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

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

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

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

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