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

خصائص الملفات المخصّصة هي أزواج المفتاح/القيمة المستخدَمة لتخزين بيانات وصفية مخصّصة لملف 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

{
  '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 على قيمة فارغة.

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