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

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

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

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

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

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

Drive API v3

"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 على "فارغ".

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