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

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

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

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

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

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

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

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، يُرجى الاطّلاع على المرجع properties.

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

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