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

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

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

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

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

الإصدار 3 من واجهة برمجة تطبيقات Drive

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

الإصدار 2 من واجهة برمجة تطبيقات Drive

{
  '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. بالنسبة إلى الإصدار 2 من Drive API، يُرجى الاطّلاع على المرجع properties.

الوصول إلى خصائص الملفات المخصّصة الخاصة

لا يمكنك استرداد المواقع الخاصة إلا باستخدام الحقل appProperties من خلال طلب تمّت مصادقته ويستخدِم رمزًا مميزًا للوصول تمّ الحصول عليه باستخدام معرّف عميل OAuth 2.0. لا يمكنك استخدام مفتاح واجهة برمجة التطبيقات لاسترداد المواقع الخاصة.