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

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

إنشاء ملف

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

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

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

استخدام مَعلمة 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.

إنشاء ملفات تتضمّن بيانات وصفية فقط

لا تحتوي الملفات التي تتضمّن البيانات الوصفية فقط على أي محتوى. بيانات التعريف هي البيانات (مثل 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.

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

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

  • الأذونات:

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

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

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

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