إنشاء الملفات وإدارتها

يوضّح هذا الدليل كيفية إنشاء الملفات وإدارتها في Google Drive باستخدام Google Drive API.

إنشاء ملف

لإنشاء ملف في Drive لا يحتوي على أي بيانات وصفية أو محتوى، استخدِم طريقة create في مصدر files بدون أي مَعلمات.

عند إنشاء الملف، تعرض الطريقة مصدر files. ويتم منح الملف kind بقيمة drive.file وid وname بقيمة "بلا عنوان" وmimeType بقيمة application/octet-stream. يتم وضع علامة على uploadType على أنّه مطلوب، ولكنّ القيمة التلقائية هي media، لذا ليس عليك توفيرها فعليًا.

لمزيد من المعلومات عن الحدود القصوى لملفات Drive، يُرجى الاطّلاع على الحدود القصوى للملفات و المجلدات.

تعرض عيّنات التعليمات البرمجية التالية كيفية إنشاء ملف بدون أي بيانات وصفية أو محتوى:

Node.js

/**
 * Create an empty file.
 * @return {string} The created file's ID.
 */
async function createEmptyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.create({});
    console.log('File ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

غيِّر القيم في السلسلة على الشكل التالي:

  • ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك

استخدام مَعلمة fields

إذا أردت تحديد الحقول التي سيتم عرضها في الاستجابة، يمكنك ضبط الـ fields مَعلمة النظام باستخدام أي طريقة من طرق مصدر الـ files. إذا لم تحدّد مَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض طريقة list سوى الحقول kind وid و name وmimeType وresourceKey لكل ملف. لعرض حقول مختلفة ، يُرجى الاطّلاع على عرض حقول معيّنة.

ملكية الملف

عند إنشاء ملف باستخدام Drive API، تعتمد الملكية على بيانات اعتماد المصادقة التي يستخدمها التطبيق بالطرق التالية:

  • حساب المستخدم (OAuth 2.0): إذا كان التطبيق يصادق نيابةً عن مستخدم، يصبح هذا المستخدم مالك الملف. بعد ذلك، يتم تخزين الملف في مجلد "ملفاتي" أو مجلد محدّد. يستهلك ذلك مساحة التخزين المتوفّرة لديهم.

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

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

لمزيد من المعلومات عن أذونات الملفات، يُرجى الاطّلاع على مشاركة الملفات والمجلدات ومساحات التخزين السحابي.

إنشاء أرقام تعريف لاستخدامها مع ملفاتك

تتيح لك طريقة generateIds في مصدر files إنشاء أرقام تعريف فريدة للملفات يمكن استخدامها عند إنشاء الملفات والمجلدات أو نسخها في Drive. يمكن أن يكون ذلك مفيدًا عندما تحتاج إلى التحكّم في أرقام تعريف الملفات من تطبيقك، بدلاً من السماح لـ Drive بتعيينها تلقائيًا.

يمكنك ضبط عدد أرقام التعريف التي يتم إنشاؤها باستخدام مَعلمة طلب البحث count. إذا لم يتم ضبط count، يتم عرض 10 أرقام تعريف تلقائيًا. الحد الأقصى لعدد أرقام التعريف التي يمكنك طلبها هو 1,000.

يمكنك أيضًا تحديد space الذي يمكن استخدام أرقام التعريف فيه و type العناصر التي يمكن استخدام أرقام التعريف لها.

بعد إنشاء رقم تعريف، يمكن تمريره إلى طريقة create أو copy من خلال الحقل id. يضمن ذلك أن يستخدم الملف الذي تم إنشاؤه أو نسخه رقم التعريف المحدّد مسبقًا.

إذا تم إنشاء الملف أو نسخه بنجاح، ستعرض عمليات إعادة المحاولة اللاحقة استجابة رمز حالة HTTP 409 Conflict ولن يتم إنشاء ملفات مكرّرة.

يُرجى العِلم أنّ أرقام التعريف التي تم إنشاؤها مسبقًا غير متاحة لإنشاء ملفات Google Workspace، باستثناء application/vnd.google-apps.drive-sdk و application/vnd.google-apps.folder نوعَي MIME. وبالمثل، لا يتمّ دعم عمليات التحميل التي تشير إلى عملية تحويل إلى تنسيق ملف Google Workspace.

تعرض عيّنات التعليمات البرمجية التالية كيفية إنشاء أرقام تعريف فريدة للملفات مسبقًا:

Node.js

/**
 * Pre-generate unique file IDs.
 */
async function generateFileIds() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.generateIds({
      count: 10,
      space: 'drive'
    });
    const ids = response.data.ids;
    console.log('Generated IDs:');
    for (const id of ids) {
      console.log(id);
    }
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl 'https://www.googleapis.com/drive/v3/files/generateIds?count=10&space=drive' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

غيِّر القيم في السلسلة على الشكل التالي:

  • ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك

إنشاء ملفات تحتوي على بيانات وصفية فقط

لا تحتوي الملفات التي تتضمّن بيانات وصفية فقط على أي محتوى. البيانات الوصفية هي بيانات (مثل name وmimeType وcreatedTime) تصف الملف. إنّ حقول مثل name لا تتأثر بالمستخدم وتظهر بالطريقة نفسها لكل مستخدم، بينما تحتوي حقول مثل viewedByMeTime على قيم خاصة بالمستخدم.

من الأمثلة على الملفات التي تتضمّن بيانات وصفية فقط مجلد بنوع MIME application/vnd.google-apps.folder. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء المجلدات وتعبئتها. مثال آخر هو اختصار يشير إلى ملف آخر على Drive بنوع MIME application/vnd.google-apps.shortcut. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء اختصار إلى ملف في Drive.

إدارة الصور المصغّرة

تساعد الصور المصغّرة المستخدمين في تحديد ملفات Drive. يمكن لـ Drive إنشاء صور مصغّرة تلقائيًا لأنواع الملفات الشائعة، أو يمكنك تقديم صورة مصغّرة تم إنشاؤها بواسطة تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على تحميل الصور المصغّرة.

نسخ ملف حالي

لنسخ ملف وتطبيق أي تعديلات مطلوبة، استخدِم طريقة copy في مصدر files. للعثور على الـ fileId الذي تريد نسخه، استخدِم طريقة الـlist.

يمكنك تطبيق التعديلات من خلال دلالات التصحيح، ما يعني أنّه يمكنك إجراء تعديلات جزئية على مصدر. يجب ضبط الحقول التي تنوي تعديلها بشكلٍ صريح في طلبك. تحتفظ أي حقول غير مضمّنة في الطلب بقيمها الحالية. لمزيد من المعلومات، يُرجى الاطّلاع على العمل مع المصادر الجزئية.

يمكنك ضبط رقم تعريف الملف المنسوخ مسبقًا باستخدام طريقة generateIds. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء أرقام تعريف لاستخدامها مع ملفاتك.

يُرجى العِلم أنّه عليك استخدام نطاق Drive API مناسب لتفويض الطلب. لمزيد من المعلومات عن نطاقات Drive، يُرجى الاطّلاع على اختيار نطاقات Google Drive API.

تعرض عيّنات التعليمات البرمجية التالية كيفية نسخ ملف وتعديل اسمه:

Node.js

/**
 * Copy an existing file.
 * @return {string} The copied file's ID.
 */
async function copyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.copy({
      fileId: 'FILE_ID',
      requestBody: {
        name: 'FILE_COPY_NAME'
      }
    });
    console.log('Copied file ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

غيِّر القيم في السلسلة على الشكل التالي:

  • FILE_ID: رقم تعريف الملف الذي تريد نسخه
  • FILE_COPY_NAME: اسم الملف الجديد

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/copy' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "name": "FILE_COPY_NAME"
 }'

غيِّر القيم في السلسلة على الشكل التالي:

  • FILE_ID: رقم تعريف الملف الذي تريد نسخه
  • ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك
  • FILE_COPY_NAME: اسم الملف الجديد

الحدود القصوى والاعتبارات

أثناء الاستعداد لنسخ الملفات، يُرجى العِلم بهذه الحدود القصوى والاعتبارات:

  • الأذونات:

    • يحدّد العنصر DownloadRestrictionsMetadata في مصدر files المستخدمين الذين يمكنهم نسخ الملف. لمزيد من المعلومات، يُرجى الاطّلاع على منع المستخدمين من تنزيل ملفك أو طباعته أو نسخه.
    • يحدّد مصدر الحقل capabilities.canCopy ما إذا كان بإمكان المستخدم نسخ ملف. لمزيد من المعلومات، يُرجى الاطّلاع على فهم إمكانات الملفات.
    • يملك المستخدم الذي أنشأ النسخة الملف المنسوخ. لا يتم تكرار أي إعدادات مشاركة أخرى من الملف المصدر. إذا تم إنشاء النسخة في مجلد مشترك، فإنّها تكتسب أذونات هذا المجلد.
    • قد تتغيّر ملكية الملف المنسوخ وقد لا تكتسب النسخة إعدادات المشاركة الخاصة بالملف الأصلي. قد تحتاج إلى إعادة ضبط هذه الإعدادات.

  • إدارة الملفات:

    • لا يمكن نسخ بعض الملفات مطلقًا، مثل الاختصارات التابعة لجهات خارجية.
    • لا يمكنك نسخ ملف إلا في مجلد رئيسي واحد. لا يمكن تحديد عدة مجلدات رئيسية. إذا لم يتم تحديد الحقل parents، يكتسب الملف أي مجلدات رئيسية يمكن اكتشافها من الملف المصدر.
    • على الرغم من أنّ المجلد هو نوع من أنواع الملفات، لا يمكنك نسخ مجلد. بدلاً من ذلك، أنشئ مجلدًا وجهة واضبط الحقل parents للملفات الحالية على المجلد الوجهة. يمكنك بعد ذلك حذف المجلد المصدر الأصلي.
    • ما لم يتم تحديد اسم ملف جديد، تنشئ طريقة copy ملفًا بالاسم نفسه الذي يحمله الملف الأصلي.
    • يمكن أن يؤدي الاستخدام المفرط لطريقة copy إلى تجاوز الحدود القصوى لحصة استخدام Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على حدود الاستخدام.

في ما يلي بعض الخطوات التالية التي يمكنك تجربتها: