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

يتناول هذا المستند اعتبارات مهمة لتسمية الملفات والعمل مع بيانات التعريف، مثل النصوص التي يمكن فهرستها والصور المصغّرة. لإدراج الملفات واستردادها، اطّلِع على مستند 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.

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

إذا كان بإمكان 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)