إدارة البيانات الوصفية للملف

يتناول هذا المستند اعتبارات مهمة لتسمية الملفات والعمل مع البيانات الوصفية مثل النصوص والصور المصغّرة القابلة للفهرسة. لإدراج الملفات واستردادها، يُرجى الاطّلاع على مرجع files.

تحديد أسماء الملفات والإضافات

يجب أن تحدد التطبيقات امتداد ملف في خاصية العنوان عند إدراج الملفات باستخدام Google Drive API. على سبيل المثال، يجب أن تحدّد عملية إدراج ملف JPEG شيئًا مثل "name": "cat.jpg" في البيانات الوصفية.

يمكن أن تتضمّن استجابات GET اللاحقة سمة fileExtension للقراءة فقط التي تم تعبئتها بالإضافة التي تم تحديدها في الأصل في السمة name. عندما يطلب مستخدم Google Drive تنزيل ملف، أو عند تنزيل الملف من خلال برنامج المزامنة، ينشئ Drive اسم ملف كاملاً (مع الإضافة) استنادًا إلى العنوان. في الحالات التي تكون فيها الإضافة غير متوفّرة، يحاول Drive تحديد الإضافة استنادًا إلى نوع MIME للملف.

حفظ نص قابل للفهرسة

يفهرس Drive تلقائيًا المستندات للبحث عندما يتعرّف على نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تحتوي على نصوص والأنواع الشائعة الأخرى. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات والفيديوهات والاختصارات)، يمكنك تحسين قابلية اكتشاف التطبيق من خلال تقديم نص قابل للفهرسة في الحقل contentHints.indexableText من الملف.

تتم فهرسة النص القابل للفهرسة بتنسيق HTML. إذا حفظت سلسلة النص القابل للفهرسة <section attribute="value1">Here's some text</section>، تتم فهرسة "إليك بعض النص"، بينما تتم فهرسة "القيمة1". لهذا السبب، إنّ حفظ XML كنص قابل للفهرسة ليس مفيدًا مثل حفظ HTML.

عند تحديد indexableText، يجب أيضًا مراعاة ما يلي:

  • الحدّ الأقصى المسموح به لحجم contentHints.indexableText هو 128 كيلوبايت.
  • دوِّن المصطلحات والمفاهيم الأساسية التي تتوقع أن يبحث عنها المستخدم.
  • لا تحاول ترتيب النص حسب الأهمية لأنّ أداة الفهرسة تنفّذ ذلك بكفاءة.
  • يجب أن يعدّل تطبيقك النص القابل للفهرسة مع كل عملية حفظ.
  • تأكَّد من أنّ النص ذو صلة بمحتوى الملف أو بياناته الوصفية.

قد تبدو هذه النقطة الأخيرة واضحة، لكنها مهمة. ليس من الجيد إضافة عبارات يتم البحث عنها بشكل شائع لإجبار الملف على الظهور في نتائج البحث. يمكن أن يؤدي ذلك إلى إحباط المستخدمين، وقد يحفزهم على حذف الملف.

تحميل صور مصغّرة

ينشئ Drive تلقائيًا صورًا مصغرة للعديد من أنواع الملفات الشائعة، مثل مستندات Google وجداول البيانات والعروض التقديمية. تساعد الصور المصغّرة المستخدم في التعرّف على ملفات Drive بشكل أفضل.

بالنسبة إلى أنواع الملفات التي يتعذّر على Drive إنشاء صورة مصغّرة عادية لها، يمكنك توفير صورة مصغّرة يتم إنشاؤها بواسطة تطبيقك. أثناء إنشاء الملف أو تعديله، يمكنك تحميل صورة مصغّرة من خلال ضبط الحقل contentHints.thumbnail على المورد files.

وهذه القيود تحديدًا هي كالآتي:

  • اضبط الحقل contentHints.thumbnail.image على عنوان URL واسم الملف بطريقة آمنة بترميز base64 (راجِع القسم RFC 4648 5).
  • اضبط الحقل contentHints.thumbnail.mimeType على نوع MIME المناسب للصورة المصغّرة.

إذا كان بإمكان Drive إنشاء صورة مصغّرة من الملف، فإنه يستخدم الصورة التي تم إنشاؤها تلقائيًا ويتجاهل أي صورة حمَّلتها. إذا لم يتمكن من إنشاء صورة مصغّرة، يتم استخدام الصورة التي تقدّمها

يجب أن تلتزم الصور المصغّرة بالقواعد التالية:

  • يمكن تحميلها بتنسيق PNG أو GIF أو JPG.
  • العرض الموصى به هو 1600 بكسل.
  • الحد الأدنى للعرض هو 220 بكسل.
  • الحد الأقصى لحجم الملف هو 2 ميغابايت.
  • ويجب أن يعدّلها التطبيق مع كل عملية حفظ.

لمزيد من المعلومات، يُرجى الاطّلاع على المرجع files.

استرداد الصور المصغّرة

يمكنك استرداد البيانات الوصفية، بما في ذلك الصور المصغّرة، لملفات Drive. يتم العثور على معلومات الصورة المصغّرة في الحقل thumbnailLink من مرجع files.

إرجاع صورة مصغّرة محدّدة

يعرض نموذج الرمز البرمجي التالي طلب طريقة files.get مع حقول متعددة كمَعلمة طلب بحث لعرض البيانات الوصفية thumbnailLink لملف محدّد. لمزيد من المعلومات، راجع عرض حقول محددة لملف.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

استبدِل FILE_ID بالرمز fileId للملف الذي تريد العثور عليه.

يعرض الطلب، إن توفّر، عنوان URL قصير الأجل إلى الصورة المصغّرة للملف. وعادةً ما يستمرّ الرابط لعدة ساعات. لا تتم تعبئة الحقل إلا عندما يتمكن التطبيق الطالب من الوصول إلى محتوى الملف. إذا لم تتم مشاركة الملف بشكل علني، يجب جلب عنوان URL الذي يتم عرضه في thumbnailLink باستخدام طلب معتمد.

إرجاع قائمة بالصور المصغّرة

يعرض نموذج الرمز البرمجي التالي طلب طريقة files.list مع حقول متعددة كمَعلمة طلب بحث لعرض بيانات thumbnailLink الوصفية لقائمة من الملفات. للحصول على مزيد من المعلومات، راجع البحث عن الملفات والمجلدات.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

لحصر نتائج البحث على نوع معيّن من الملفات، يمكنك تطبيق سلسلة طلب بحث لضبط النوع MIME. على سبيل المثال، يوضح نموذج التعليمات البرمجية التالي كيفية قصر القائمة على ملفات جداول بيانات Google. لمزيد من المعلومات حول أنواع MIME، يُرجى الاطّلاع على أنواع MIME المتوافقة مع Google Workspace وGoogle Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)