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

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

نظرة عامة على البيانات الوصفية

في Google Drive API، يمثّل المورد files البيانات الوصفية. على عكس واجهات برمجة التطبيقات التي تكون فيها البيانات الوصفية عبارة عن عنصر فرعي، تتعامل واجهة Drive API مع مورد files بأكمله كبيانات وصفية. يمكنك الوصول إلى البيانات الوصفية مباشرةً من خلال الطريقتَين get أو list في المرجع files.

تلقائيًا، لا يعرض الإجراءان get وlist سوى مجموعة جزئية من الحقول. لاسترداد بيانات معيّنة، يجب تحديد fields مَعلمة النظام في طلبك. في حال عدم تضمينها، يعرض الخادم مجموعة فرعية تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، تعرض الطريقة list الحقول kind وid وname وmimeType وresourceKey فقط لكل ملف. لعرض حقول مختلفة، راجِع عرض حقول محدّدة.

بالإضافة إلى ذلك، يعتمد ظهور البيانات الوصفية على دور المستخدم في الملف. لا يحدّد المرجع permissions الإجراءات المسموح بها للمستخدم على ملف أو مجلد. بدلاً من ذلك، يحتوي المورد files على مجموعة من الحقول المنطقية capabilities. تستمد واجهة Google Drive API هذه capabilities من مصدر permissions المرتبط بالملف أو المجلد. لمزيد من المعلومات، يُرجى الاطّلاع على التعرّف على إمكانات الملفات.

توفّر واجهة Drive API نطاقَين محدودَين للبيانات الوصفية: drive.metadata وdrive.metadata.readonly. يتيح لك النطاق drive.metadata الاطّلاع على البيانات الوصفية للملفات وإدارتها، بينما يكون النطاق drive.metadata.readonly للقراءة فقط. وكلاهما يحظران بشكل صارم الوصول إلى محتوى الملفات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار نطاقات Google Drive API.

أخيرًا، تحقَّق دائمًا من منطقك بشأن الأذونات والنطاقات. على سبيل المثال، قد يملك المستخدم ملفًا لديه أذونات كاملة، ولكن ستمنع واجهة Drive API محاولات تعديل الملف أو تنزيله إذا كان تطبيقك لديه النطاق drive.metadata.readonly فقط.

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

يجب أن تحدّد التطبيقات امتداد الملف في السمة name عند إدراج الملفات باستخدام 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.

إرجاع صورة مصغّرة معيّنة

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

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

استبدِل FILE_ID بـ fileId الخاص بالملف الذي تريد البحث عنه.

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

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

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

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

لحصر نتائج البحث بنوع ملف معيّن، طبِّق سلسلة طلب بحث لضبط نوع MIME. على سبيل المثال، يوضّح نموذج الرمز التالي كيفية حصر القائمة على ملفات &quot;جداول بيانات Google&quot;. لمزيد من المعلومات عن أنواع 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)