يتناول هذا المستند اعتبارات مهمة بشأن تسمية الملفات والتعامل مع بيانات التعريف، مثل النصوص القابلة للفهرسة والصور المصغّرة. لإدراج الملفات واستردادها، راجِع مرجع 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على الصورة المرمّزة باستخدام base64 والمتوافقة مع عناوين URL وأسماء الملفات (راجِع القسم 5 من RFC 4648). - اضبط الحقل
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)