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

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