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

يتناول هذا المستند اعتبارات مهمة لتسمية الملفات والعمل مع البيانات الوصفية مثل النصوص والصور المصغّرة القابلة للفهرسة. لإدراج الملفات واستردادها، راجع المرجع 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>، ثم "إليك بعض الأمثلة نصّ" تمت فهرسة، ولكن "value1" لا. ولهذا السبب، فإنّ حفظ XML كمحتوى قابل للفهرسة. النص ليس مفيدًا مثل حفظ HTML.

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

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

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

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

ينشئ Drive تلقائيًا صورًا مصغّرة للعديد من الملفات الشائعة. مثل "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من 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)