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

يوضّح هذا الدليل كيفية إنشاء الملفات وإدارتها في 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 system مع أي طريقة من طرق المورد 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: اسم الملف الجديد

نسخ التعليقات

لنسخ التعليقات والاقتراحات عند نسخ ملف "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google"، اضبط مَعلمة طلب البحث copyComments على true. تتضمّن النسخ التعليقات المفتوحة فقط (التعليقات التي لم يتم حلّها). بالنسبة إلى أنواع الملفات الأخرى، يتجاهل Drive هذه المَعلمة.

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

الحدود والاعتبارات

عند الاستعداد لنسخ الملفات، ضَع في اعتبارك هذه الحدود والاعتبارات:

  • الأذونات:

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

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

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

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